Most common docblock for Delphi and/or FreePascal code

Question

I'm quite familiar with PHP dockblocks since it's been my job for the last 15+ years.

/**
  * Description
  *
  * @tag bla bla
  * @tag more bla bla
  */

What I'm trying to understand is if there is a standard like that for Delphi and/or FreePascal.

From my analysis on an awful lot of code I never seen any, but I could be dead wrong.

score 15 · Accepted Answer · edited Mar 24 '19 at 17:28

Delphi documentation tools

Using the XMLDoc tool for API documentation and HelpInsight with Delphi 2005 http://edn.embarcadero.com/article/32770

XML Documentation in Delphi 2006 http://tondrej.blogspot.com/2006/03/xml-documentation-in-delphi-2006.html

DelphiCodeToDoc http://dephicodetodoc.sourceforge.net/

Doc-O-Matic http://www.doc-o-matic.com/examplesourcecode.html

PasDoc http://pasdoc.sipsolutions.net/

Pascal Browser http://www.peganza.com/

Doxygen http://www.doxygen.nl/

Pas2Dox http://sourceforge.net/projects/pas2dox/

JADD - Just Another DelphiDoc http://delphidoc.sourceforge.net/

Stackoverflow discussion

Is there a Delphi code documentor that supports current Delphi syntax? https://stackoverflow.com/questions/673248/is-there-a-delphi-code-documentor-that-supports-current-delphi-syntax

Code documentation for delphi similar to javadoc or c# xml doc Code documentation for delphi similar to javadoc or c# xml doc

Documenting Delphi https://stackoverflow.com/questions/33336/documenting-delphi

score 7 · Answer 2 · answered Apr 15 '09 at 08:53

7

Latest Delphis support parsing of XML documentation. They also use this information in hints (for example if you move the mouse cursor over a method name).

I'm using this template for method documentation:

///<summary></summary>
///<param name=''></param>
///<returns></returns>
///<exception cref=""></exception>
///<since>2009-04-15</since>

answered Apr 15 '09 at 08:53

gabr

26,580
9
75
141

1

@gabr: Could you include the link for the complete syntax on that please? – Gustavo Carreno Apr 15 '09 at 12:37
@gabr: could you at least give use your own memory's neurons mapping ? ;) – Gustavo Carreno Apr 15 '09 at 14:46
I'm only using the tags mentioned above plus and in unit header. – gabr Apr 15 '09 at 15:18

score 1 · Answer 3 · edited Mar 25 '19 at 18:08

1

It looks like doxygen has a tool which can be used in conjunction to document Pascal and Delphi code. Maybe that will help you.

edited Mar 25 '19 at 18:08

albert

8,285
3
19
32

answered Apr 15 '09 at 08:49

1800 INFORMATION

131,367
29
160
239

+1 I use doxygen and pas2dox in all my commercial Delphi / Free Pascal libraries, commenting in JavaDoc style works like a charm – mjn Apr 15 '09 at 12:32

onnodb · Answer 4 · 2009-06-10T10:31:49.797

1

On a project I'm currently working on, we're using DelphiCodeToDoc, which works reasonably well. Its syntax looks like this:

type
  {* This is an example class }
  TMyClass = class
  private
  protected
  public
    {* Does some twiddling with AParam, and returns the result as String
       @param AParam Input value
       @return AParam incremented by 2, as String
       @throws Exception 'Boo' if it's full moon }
    function MyFunction(AParam: Integer): String;
  end;

edited Jun 10 '09 at 10:31

answered Apr 15 '09 at 09:18

onnodb

5,241
1
32
41

I know this is just an example and I'm nit-picking, but a procedure does not return values right? ;) – Gustavo Carreno Jun 10 '09 at 08:43
Lol :D Yeah, of course you're completely right. Corrected my answer. – onnodb Jun 10 '09 at 10:32

score 1 · Answer 5 · answered Apr 26 '09 at 17:14

1

I prefer docs outside of the source (it always gets messy), and use the excellent fpdoc that comes with FPC. (FPC's own docs are written in it).

answered Apr 26 '09 at 17:14

score 0 · Answer 6 · answered Apr 15 '09 at 14:18

There are several standards, usually depending on the documentation tool being used. We use PasDoc, so we adhere mostly to its format http://pasdoc.sipsolutions.net/ which is based on JavaDoc.

Alternatively, there is XMLDoc as gabr pointed out and there are quite a few other tools, most having similar syntax with subtle differences.

Most common docblock for Delphi and/or FreePascal code

6 Answers6

Delphi documentation tools

Stackoverflow discussion