[fpc-devel] [RFC] fpdoc output comment from the source

[Mark de Wever]

Hi all,

I like to put a lot of comment in the source and I would like fpdoc to
output this comment into the output files. I wrote a small patch to do
this with types, it puts all the comment in front of a type declaration 
into the output html as section "Comment text". 

Since I'm not really familiar with both fpdoc and passrc internals I
don't know whether this is the best way to do it, could someone
enlighten me?

Would people like to include this option in fpdoc, behind the option
--include-comment?

Greets,

Mark de Wever

PS comment of the type (* comment *) don't work, don't know why and
didn't look into it yet.
-------------- next part --------------
Index: utils/fpdoc/dglobals.pp
===================================================================
--- utils/fpdoc/dglobals.pp	(revision 1871)
+++ utils/fpdoc/dglobals.pp	(working copy)
@@ -49,6 +49,7 @@
   SDocUnitOverview           = 'Overview of unit ''%s''';
   SDocOverview               = 'Overview';
   SDocSearch                 = 'Search';
+  SDocCommentText            = 'Comment text';
   SDocDeclaration            = 'Declaration';
   SDocDescription            = 'Description';
   SDocErrors                 = 'Errors';
Index: utils/fpdoc/dw_html.pp
===================================================================
--- utils/fpdoc/dw_html.pp	(revision 1871)
+++ utils/fpdoc/dw_html.pp	(working copy)
@@ -183,6 +183,7 @@
       AShFlags: Byte): Byte;
     Procedure AppendShortDescr(AContext : TPasElement;Parent: TDOMNode; DocNode : TDocNode);
     procedure AppendShortDescr(Parent: TDOMNode; Element: TPasElement);
+    procedure AppendCommentText(const AText: DOMString);
     procedure AppendDescr(AContext: TPasElement; Parent: TDOMNode;
       DescrNode: TDOMElement; AutoInsertBlock: Boolean);
     procedure AppendDescrSection(AContext: TPasElement; Parent: TDOMNode;
@@ -1311,6 +1312,14 @@
   AppendShortDescr(Element,Parent,Engine.FindDocNode(Element));
 end;
 
+procedure THTMLWriter.AppendCommentText(const AText: DOMString);
+begin
+  if( AText <> '' ) then begin
+  	AppendText(CreateH2(BodyElement), SDocCommentText);
+  	AppendText(CreatePara(BodyElement), AText);
+	end;
+end;
+
 procedure THTMLWriter.AppendDescr(AContext: TPasElement; Parent: TDOMNode;
   DescrNode: TDOMElement; AutoInsertBlock: Boolean);
 begin
@@ -2269,6 +2278,7 @@
   AppendShortDescr(CreatePara(BodyElement), AType);
   AppendText(CreateH2(BodyElement), SDocDeclaration);
   AppendSourceRef(AType);
+  AppendCommentText(AType.CommentText);
 
   TableEl := CreateTable(BodyElement);
   TREl := CreateTR(TableEl);
Index: fcl/passrc/pastree.pp
===================================================================
--- fcl/passrc/pastree.pp	(revision 1871)
+++ fcl/passrc/pastree.pp	(working copy)
@@ -76,6 +76,7 @@
     FRefCount: LongWord;
     FName: string;
     FParent: TPasElement;
+    FCommentText: string;
   public
     SourceFilename: string;
     SourceLinenumber: Integer;
@@ -91,6 +92,7 @@
     property RefCount: LongWord read FRefCount;
     property Name: string read FName write FName;
     property Parent: TPasElement read FParent;
+    property CommentText:string read FCommentText write FCommentText; // comment before the element
   end;
 
   TPasSection = class(TPasElement)
@@ -514,6 +516,7 @@
   inherited Create;
   FName := AName;
   FParent := AParent;
+  FCommentText := '';
 end;
 
 procedure TPasElement.AddRef;
Index: fcl/passrc/pparser.pp
===================================================================
--- fcl/passrc/pparser.pp	(revision 1871)
+++ fcl/passrc/pparser.pp	(working copy)
@@ -95,6 +95,7 @@
     FFileResolver: TFileResolver;
     FScanner: TPascalScanner;
     FEngine: TPasTreeContainer;
+    FCurTokenCommentText: string;
     FCurToken: TToken;
     FCurTokenString: String;
     // UngetToken support:
@@ -152,6 +153,7 @@
     property Scanner: TPascalScanner read FScanner;
     property Engine: TPasTreeContainer read FEngine;
 
+    property CurTokenCommentText: string read FCurTokenCommentText;
     property CurToken: TToken read FCurToken;
     property CurTokenString: String read FCurTokenString;
   end;
@@ -251,9 +253,13 @@
       Dec(FTokenBufferIndex);
     end;
     // Fetch new token
+    FCurTokenCommentText:='';
     try
       repeat
         FCurToken := Scanner.FetchToken;
+	if( FCurToken = tkComment )then begin
+		FCurTokenCommentText:=FCurTokenCommentText+Scanner.CurTokenString;
+		end;
       until not (FCurToken in [tkWhitespace, tkComment]);
     except
       on e: EScannerError do
@@ -869,6 +875,7 @@
 function TPasParser.ParseTypeDecl(Parent: TPasElement): TPasType;
 var
   TypeName: String;
+  Comment: String;
 
   procedure ParseRange;
   begin
@@ -891,6 +898,7 @@
 
 begin
   TypeName := CurTokenString;
+  Comment := CurTokenCommentText;
   ExpectToken(tkEqual);
   NextToken;
   HadPackedModifier := False;     { Assume not present }
@@ -1092,6 +1100,8 @@
       ParseRange;
     end;
   end;
+  if( Result <> nil )then
+    Result.CommentText:=Comment;
 end;
 
 // Starts after the variable name