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.

Efficiency

Answer 1

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

Perot

Answer 2

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>

Saddletree

@gabr: Could you include the link for the complete syntax on that please? – Efficiency

@gabr: could you at least give use your own memory's neurons mapping ? ;) – Efficiency

I'm only using the tags mentioned above plus <author> and <remarks> in unit header. – Saddletree

Answer 3

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

Burst

+1 I use doxygen and pas2dox in all my commercial Delphi / Free Pascal libraries, commenting in JavaDoc style works like a charm – Aryl

Answer 4

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;

Interviewee

I know this is just an example and I'm nit-picking, but a procedure does not return values right? ;) – Efficiency

Lol :D Yeah, of course you're completely right. Corrected my answer. – Interviewee

Answer 5

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).

Lozier

Answer 6

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.

Bondman