Delphi Documentation Guidelines

Written by Baoquan Zuo on . Posted in Announcements

1. Preface:

When we want to learn a code library, we must read its documentation at first. A professional documentation will help us easily get the key points and understand the design intention of the author. It is no doubtful that one of the most impressive examples is MSDN.

On the other hand, when we play the role of an author, we also need to write documentation to explain our code and design remarks, especially when working together with other developers.

2. Introduction:

Delphi Documentation Guidelines has 23 pages. It targets the XML Documentation and tells you how to write xml documentation for your code. It also provides detailed XML tag reference, examples and examples out (snapshot).

3. Table of Contents:

Here lists the Table of Contents of the document:

Table of Contents

1. Copyright 3

2. Acknowledgements 3

3. Revision History 3

4. Overview 4

5. XML Documentation 5

5.1 Introduction 5

5.2 Section Tags 6

5.3 Block Tags 6

5.4 Inline Tags 7

5.5 Tag Usage 7

6. XML Tag Reference 7

6.1 <c> 7

6.2 <code> 8

6.3 <example> 8

6.4 <exception> 9

6.5 <include> 10

6.6 <list> 10

6.7 <note> 12

6.8 <para> 13

6.9 <param> 14

6.10 <paramref> 14

6.11 <permission> 15

6.12 <preliminary> 15

6.13 <remarks> 15

6.14 <returns> 16

6.15 <see> 16

6.16 <seealso> 16

6.17 <summary> 17

6.18 <threadsafety> 18

6.19 <typeparam> 18

6.20 <typeparamref> 19

6.21 <value> 19

7. Write Documentation 21

8. Generate Documentation 23

9. References 23

4. Download:

http://www.devjetsoftware.com/downloads/Delphi-Documentation-Guidelines.pdf

This is the initial release. Please feel free to download it. I hope that you can understand xml documentation better with this document.

If there is anything missed or wrong, please let me know.

Trackback from your site.

Comments (8)

  • Bob Swart

    |

    Nice document, good details. Note that I’ve written a Live Template for Delphi 2007 and higher that supports the manual addition of the /// tags in source code.

    See http://www.drbob42.com/examines/examinA0.htm for my article (which is also updated and refreshed in my Delphi XE Development Essentials manual). I will add a reference to your website here for the PDF file with more details on the Delphi documentation options.

    Reply

  • Paul

    |

    Hah, It’s you – Bob, Thank you so much!

    I have noticed the article and I will update the guidelines for the more details. : )

    Looking forward to your Delphi XE Development Essentials manual, too.

    Reply

    • Paul

      |

      Thanks for the link, I have read it. I am going to release a customized one to support more tags mentioned in the guidelines.

      Reply

  • Bas

    |

    Downloadlink of the guidelines doc is no longer valid :-(

    Reply

    • Baoquan Zuo

      |

      Hi, Could you tell us which link is invalid? I have just tested and the guidelines is still valid.

      Reply

  • Francisco Dueñas

    |

    Hi I think He is talking about this same page in the lat point where it says:
    4. Download:
    {title} ({hits})

    Reply

    • Baoquan Zuo

      |

      Thanks, I have fixed the broken link in this topic which was missed.

      Reply

Leave a comment