[Pasdoc-main] What do you think about a @file option?

[silvioprog <sil...@gm...>]

Hello,

I'm using PasDoc to generate the documentation of my new framework, and I'm
very happy, because PasDoc is a great tool, generating the documentation
from a code that compiles with Free Pascal and Delphi. Nice! =)

However, in some situations, I have a long comment in the source, and it
disrupts the maintenance of the source, e.g:

[code]
{
  Copyright (C) 2015 Brook developers.

  This file is part of "Brook framework".

  See the file LICENSE.txt, included in this distribution,
  for details about the copyright.

  This library is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.


----------------------------------------------------------------------------
}

{ @abstract(Provides root objects for the Brook framework.)
  @author(Silvio Clecio - <sil...@gm...>)
  @author(Luciano Souza - <luc...@gm...>) }

unit Brook.Lang;

{$I Brook.Lang.inc}

interface

uses
{$IFNDEF FPC}
  Windows,
{$ENDIF}
  SysUtils;

type
  { @abstract(The root object of the Brook class hierarchy.) }
  TBrookObject = class(TObject)
  public
    { Creates an instance of its class. }
    constructor Create; virtual;
    { Returns the class's unit name concatenated with the class name.
Example:

      @longCode(#
      begin
        WriteLn(TBrookObject.QualifiedClassName); // displays
Brook.Lang.TBrookObject
        ...
      #)}
    class function QualifiedClassName: string;

...

[/code]

So, what do you think to use something like this:

Content of "Copyright.txt" (in a folder like "../Docs/TXT"):


*Copyright (C) 2015 Brook developers.*

*This file is part of "Brook framework".*

*See the file LICENSE.txt, included in this distribution,*
*for details about the copyright.*

*This library is distributed in the hope that it will be useful,*
*but WITHOUT ANY WARRANTY; without even the implied warranty of*
*MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.*

Content of "Authors.txt":

*@abstract(Provides root objects for the Brook framework.)*
*@author(Silvio Clecio - <sil...@gm... <sil...@gm...>>)*
*@author(Luciano Souza - <luc...@gm... <luc...@gm...>>)*

Content of "TBrookObject.QualifiedClassName.txt":

*Returns the class's unit name concatenated with the class name. Example:*

*  @longCode(#*
*  begin*
*    WriteLn(TBrookObject.QualifiedClassName); // displays
Brook.Lang.TBrookObject*
*    ...*
*  #)*

So, using this files and a @file tag, I could use it as:

{ @file "Copyright.txt" }
{ @file "Authors.txt" }

unit Brook.Lang;

{$I Brook.Lang.inc}

interface

uses
{$IFNDEF FPC}
  Windows,
{$ENDIF}
  SysUtils;

type
  { @abstract(The root object of the Brook class hierarchy.) }
  TBrookObject = class(TObject)
  public
    { @file }
    class function QualifiedClassName: string;

Using this command:

$ pasdoc --doc-source-path=../Doc/TXT/ ...

Or, to use without the extra param above:

    { @file "../Doc/TXT/TBrookObject.QualifiedClassName.txt" }
    class function QualifiedClassName: string;

Or:

{ @dir "/Docs/TXT/" }
{ @file "Copyright.txt" }
{ @file "Authors.txt" }

unit Brook.Lang;

{$I Brook.Lang.inc}

    { @file "TBrookObject.QualifiedClassName.txt" }
    class function QualifiedClassName: string;

Or:

    { @file }
    class function QualifiedClassName: string;

@dir Specify the default directory used by @file tag.
@file Specify a file wich will used as documentation.

You can use "@file 'your-doc.file.txt'" or "@file", this last option will
search the file containing the class and method name like
"TMyClass.MyMethod.txt" in current directory or specified via @dir.

Is it an good idea or I'm daydreaming? =/

Thank you!

-- 
Silvio Clécio
My public projects - github.com/silvioprog