[lazarus] Source Code Procedures

[michael at tfdec1.fys.kuleuven.ac.be]

On Sat, 17 Jul 1999, Stefan Hille wrote:

> Hi!
> 
> On Fri, Jul 16, 1999 at 11:29:53PM -0500, Cliff Baeseman wrote:
> > Gents
> > 
> >    Do you mind if I put in procedure seperators like I did in the controls
> > unit?
> > 
> > I always comment and put in procedure seperators like this...
> > 
> > {-------------------------------------------------------------------}
> > {TMyType.MyMethod    "comments"                        }
> > {-------------------------------------------------------------------}
> > Procedure TMyType.MyMethod;
> > begin
> > end;
> > 
> > Is anyone opposed to this style? I think it makes it easy to read the code
> > in a black and white editor.
> 
> It's OK, but we should consider if we also wanna put some kind of
> formalized documentation into these comments. I'm not absolutely sure if
> this is a good idea in general, but in the current state (where nobody
> wants's to maintain a separate documentations file) it could be helpful.
> 
> In the long run we can extract those comments again with a simple parser
> and convert it to latex or something else.
> 
> example:
> 
>  {-------------------------------------------------------------------}
>  {@@func TMyType.MyMethod                            }
>  {                                                   } 
>  { This function is useless.                         } 
>  {                                                   } 
>  { @@parms   owner: the owner of ...                 } 
>  {           i:     not used by now                  } 
>  {                                                   }
>  { @@returns  NIL                                    } 
>  {-------------------------------------------------------------------}
>  function TMyType.MyMethod (var owner : TComponent; i : integer) : pointer;
>  begin
>     result := NIL;   
>  end. 

In that case, consider 'pasdoc' it's written for FPC and does exactly this;
it transforms source comments into HTML or Tex documentation; complete with
cross-references and all.

You can find a URL on the FPC webpage.

Michael.