* Added functionality to add (and show) notes

git-svn-id: trunk@20304 -

utils/fpdoc/dglobals.pp

@@ -82,6 +82,7 @@ resourcestring
   SDocVisibility             = 'Visibility';
   SDocOpaque                 = 'Opaque type';
   SDocDateGenerated          = 'Documentation generated on: %s';
+  SDocNotes                  = 'Notes';
   
   // Topics
   SDocRelatedTopics = 'Related topics';
@@ -239,6 +240,7 @@ type
     FErrorsDoc: TDOMElement;
     FSeeAlso: TDOMElement;
     FFirstExample: TDOMElement;
+    FNotes : TDomElement;
     FLink: String;
     FTopicNode : Boolean;
     FRefCount : Integer;
@@ -263,6 +265,7 @@ type
     Property Version : TDomElement Read FVersion;
     property SeeAlso: TDOMElement read FSeeAlso;
     property FirstExample: TDOMElement read FFirstExample;
+    property Notes : TDOMElement read FNotes;
     property Link: String read FLink;
     Property TopicNode : Boolean Read FTopicNode;
     Property RefCount : Integer Read FRefCount;
@@ -1366,7 +1369,9 @@ procedure TFPDocEngine.AddDocFile(const AFilename: String;DontTrim:boolean=false
           Result.FSeeAlso := TDOMElement(Subnode)
         else if (Subnode.NodeName = 'example') and
           not Assigned(Result.FirstExample) then
-          Result.FFirstExample := TDOMElement(Subnode);
+          Result.FFirstExample := TDOMElement(Subnode)
+        else if (Subnode.NodeName = 'notes') then
+          Result.FNotes := TDOMElement(Subnode);
       end;
       Subnode := Subnode.NextSibling;
     end;

utils/fpdoc/dw_html.pp

@@ -137,6 +137,8 @@ type
     function CreateWarning(Parent: TDOMNode): THTMLElement;
 
     // Description node conversion
+    Procedure DescrEmitNotesHeader(AContext : TPasElement); override;
+    Procedure DescrEmitNotesFooter(AContext : TPasElement); override;
     procedure PushOutputNode(ANode: TDOMNode);
     procedure PopOutputNode;
     procedure DescrWriteText(const AText: DOMString); override;
@@ -188,7 +190,6 @@ type
     procedure DescrBeginTableCell; override;
     procedure DescrEndTableCell; override;
 
-
     procedure AppendText(Parent: TDOMNode; const AText: DOMString);
     procedure AppendNbSp(Parent: TDOMNode; ACount: Integer);
     procedure AppendSym(Parent: TDOMNode; const AText: DOMString);
@@ -976,6 +977,17 @@ begin
   Result['class'] := 'warning';
 end;
 
+procedure THTMLWriter.DescrEmitNotesHeader(AContext: TPasElement);
+begin
+  AppendText(CreateH2(BodyElement), SDocNotes);
+  PushOutputNode(BodyElement);
+end;
+
+procedure THTMLWriter.DescrEmitNotesFooter(AContext: TPasElement);
+begin
+  PopOutPutNode;
+end;
+
 procedure THTMLWriter.PushOutputNode(ANode: TDOMNode);
 begin
   OutputNodeStack.Add(CurOutputNode);
@@ -2187,6 +2199,8 @@ begin
 
     // Append examples, if present
     AppendExampleSection(AElement,DocNode);
+    // Append notes, if present
+    ConvertNotes(AElement,DocNode.Notes);
     end;
 end;
 
@@ -2210,6 +2224,7 @@ begin
     AppendSeeAlsoSection(AElement,DocNode);
     CreateTopicLinks(DocNode,AElement);
     AppendExampleSection(AElement,DocNode);
+    ConvertNotes(AElement,DocNode.Notes);
     end;
 end;
 
@@ -2545,6 +2560,7 @@ procedure THTMLWriter.CreateModulePageBody(AModule: TPasModule;
       begin
       if Assigned(DocNode.Descr) then
         AppendDescrSection(AModule, BodyElement, DocNode.Descr, SDocOverview);
+      ConvertNotes(AModule,DocNode.Notes);
       CreateTopicLinks(DocNode,AModule);
       end;
   end;

utils/fpdoc/dwlinear.pp

@@ -412,6 +412,7 @@ begin
     begin
       WriteSeeAlso(DocNode);
     end;
+    ConvertNotes(ClassDecl,DocNode.Notes);
   end;
 
   // Write Interfaces Overview;
@@ -714,6 +715,7 @@ begin
     begin
     StartSection(SDocOverview);
     WriteDescr(ASection.Parent, DocNode.Descr);
+    ConvertNotes(ASection.Parent,DocNode.Notes);
     end;
 end;
 
@@ -730,6 +732,7 @@ begin
     WriteDescr(Package, DocNode.Descr);
     end;
   WriteSeeAlso(DocNode);
+  ConvertNotes(Nil,DocNode.Notes);
   ProcessTopics(DocNode,1);
 end;
 
@@ -772,6 +775,7 @@ begin
   If Assigned(Node.Descr) then
     WriteDescr(Element,Node.Descr);
   WriteSeeAlso(Node);
+  ConvertNotes(Element,Node.Notes);
   If Level<3 then
     begin
     SubNode:=Node.FirstChild;
@@ -889,6 +893,7 @@ begin
         Writeln(Format('%s : ',[SDocVersion]));
         WriteDescr(TypeDecl, DocNode.Version);
         end;
+      ConvertNotes(TypeDecl,DocNode.Notes);
       DescrEndParagraph;
       end;
   end;
@@ -919,6 +924,7 @@ begin
         begin
         Writeln(Format('%s : ',[SDocVersion]));
         WriteDescr(VarDecl, DocNode.Version);
+        ConvertNotes(VarDecl,DocNode.Notes);
         end;
       DescrEndParaGraph;
     end;
@@ -991,6 +997,7 @@ begin
       WriteSeeAlso(DocNode);
       EndProcedure;
       WriteExample(DocNode);
+      ConvertNotes(ProcDecl,DocNode.Notes);
       end
      else
       EndProcedure;
@@ -1105,6 +1112,7 @@ begin
         WriteDescr(PropDecl, lNode.Version);
         end;
       WriteSeeAlso(lNode);
+      ConvertNotes(PropDecl,lNode.Notes);
       EndProperty;
       WriteExample(lNode);
     end

utils/fpdoc/dwriter.pp

@@ -69,6 +69,7 @@ type
 
   TFPDocWriter = class
   private
+    FEmitNotes: Boolean;
     FEngine  : TFPDocEngine;
     FPackage : TPasPackage;
     FTopics  : TList;
@@ -88,6 +89,7 @@ type
     function IsDescrNodeEmpty(Node: TDOMNode): Boolean;
     function IsExtShort(Node: TDOMNode): Boolean;
     function ConvertShort(AContext: TPasElement; El: TDOMElement): Boolean;
+    function ConvertNotes(AContext: TPasElement; El: TDOMElement): Boolean; virtual;
     function ConvertBaseShort(AContext: TPasElement; Node: TDOMNode): Boolean;
     procedure ConvertBaseShortList(AContext: TPasElement; Node: TDOMNode;
       MayBeEmpty: Boolean);
@@ -102,7 +104,9 @@ type
     function ConvertSimpleBlock(AContext: TPasElement; Node: TDOMNode): Boolean;
     Function FindTopicElement(Node : TDocNode): TTopicElement;
     Procedure ConvertImage(El : TDomElement);
-    
+
+    Procedure DescrEmitNotesHeader(AContext : TPasElement); virtual;
+    Procedure DescrEmitNotesFooter(AContext : TPasElement); virtual;
     procedure DescrWriteText(const AText: DOMString); virtual; abstract;
     procedure DescrBeginBold; virtual; abstract;
     procedure DescrEndBold; virtual; abstract;
@@ -170,6 +174,7 @@ type
     Procedure FPDocError(Fmt : String; Args : Array of Const);
     Function  ShowMember(M : TPasElement) : boolean;
     Procedure GetMethodList(ClassDecl: TPasClassType; List : TStringList);
+    Property EmitNotes : Boolean Read FEmitNotes Write FEmitNotes;
   end;
 
   TFPDocWriterClass = Class of TFPDocWriter;
@@ -346,7 +351,7 @@ begin
   Inherited;
 end;
 
-function TFPDocWriter.InterpretOption(Const Cmd,Arg : String): Boolean;
+function TFPDocWriter.InterpretOption(const Cmd, Arg: String): Boolean;
 begin
   Result:=False;
 end;
@@ -357,7 +362,7 @@ begin
   Result := ''; //Output must not contain an extension.
 end;
 
-Class procedure TFPDocWriter.Usage(List: TStrings);
+class procedure TFPDocWriter.Usage(List: TStrings);
 begin
   // Do nothing.
 end;
@@ -378,7 +383,8 @@ begin
     end;
 end;
 
-Procedure TFPDocWriter.DescrWriteImageEl(const AFileName, ACaption,ALinkName : DOMString); 
+procedure TFPDocWriter.DescrWriteImageEl(const AFileName, ACaption,
+  ALinkName: DOMString);
 
 begin
   DoLog('%s : No support for images yet: %s (caption: "%s")',[ClassName,AFileName,ACaption]);
@@ -482,6 +488,45 @@ begin
   Result := True;
 end;
 
+function TFPDocWriter.ConvertNotes(AContext: TPasElement; El: TDOMElement
+  ): Boolean;
+
+Var
+  L : TFPList;
+  N : TDomNode;
+  I : Integer;
+
+begin
+  Result:=Assigned(El) and EmitNotes;
+  If Not Result then
+    exit;
+  L:=TFPList.Create;
+  try
+    N:=El.FirstChild;
+    While Assigned(N) do
+      begin
+      If (N.NodeType=ELEMENT_NODE) and (N.NodeName='note') then
+        L.Add(N);
+      N:=N.NextSibling;
+      end;
+    Result:=L.Count>0;
+    If Not Result then
+      exit;
+    DescrEmitNotesHeader(AContext);
+    DescrBeginUnorderedList;
+    For i:=0 to L.Count-1 do
+      begin
+      DescrBeginListItem;
+      ConvertExtShortOrNonSectionBlocks(AContext, TDOMNode(L[i]).FirstChild);
+      DescrEndListItem;
+      end;
+    DescrEndUnorderedList;
+    DescrEmitNotesFooter(AContext);
+  finally
+    L.Free;
+  end;
+end;
+
 function TFPDocWriter.ConvertBaseShort(AContext: TPasElement;
   Node: TDOMNode): Boolean;
 
@@ -1044,6 +1089,20 @@ begin
   DescrWriteImageEl(FN,Cap,LinkName);
 end;
 
+procedure TFPDocWriter.DescrEmitNotesHeader(AContext: TPasElement);
+begin
+  DescrWriteLinebreak;
+  DescrBeginBold;
+  DescrWriteText(SDocNotes);
+  DescrEndBold;
+  DescrWriteLinebreak;
+end;
+
+procedure TFPDocWriter.DescrEmitNotesFooter(AContext: TPasElement);
+begin
+  DescrWriteLinebreak;
+end;
+
 
 Constructor TTopicElement.Create(const AName: String; AParent: TPasElement);
 

utils/fpdoc/fpdoc.pp

@@ -309,6 +309,8 @@ begin
       FCreator.Verbose:=true
     else if (Cmd = '-n') or (Cmd = '--dry-run') then
       FDryRun:=True
+    else if (Cmd = '-t') or (Cmd = '--emit-notes') then
+      FCreator.Options.EmitNotes := True
     else if Cmd = '--content' then
       SelectedPackage.ContentFile := Arg
     else if Cmd = '--import' then

utils/fpdoc/fpdocproj.pas

@@ -50,6 +50,7 @@ Type
     FBackEndoptions: TStrings;
     FCPUTarget: String;
     FDefaultPackageName: String;
+    FEmitNotes: Boolean;
     FFormat: String;
     FHidePrivate: Boolean;
     FHideProtected: Boolean;
@@ -79,6 +80,7 @@ Type
     Property MoDir : String Read FMoDir Write FMODir;
     Property DefaultPackageName : String Read FDefaultPackageName Write FDefaultPackageName;
     Property DontTrim : Boolean Read FDontTrim Write FDontTrim;
+    Property EmitNotes : Boolean Read FEmitNotes Write FEmitNotes;
   end;
 
   { TFPDocProject }

utils/fpdoc/fpdocxmlopts.pas

@@ -34,12 +34,12 @@ Type
 Function IndexOfString(S : String; List : Array of string) : Integer;
 
 Const
-  OptionCount = 11;
+  OptionCount = 12;
   OptionNames : Array[0..OptionCount] of string
          = ('hide-protected','warn-no-node','show-private',
             'stop-on-parser-error', 'ostarget','cputarget',
             'mo-dir','parse-impl','format', 'language',
-            'package','dont-trim');
+            'package','dont-trim','emit-notes');
 
 implementation
 
@@ -216,6 +216,7 @@ begin
         9 : Options.Language:=v;
         10 : Options.DefaultPackageName:=V;
         11 : Options.DontTrim:=TrueValue(V);
+        12 : Options.EmitNotes:=TrueValue(V);
       else
         Options.BackendOptions.add('--'+n);
         Options.BackendOptions.add(v);
@@ -283,6 +284,7 @@ begin
   AddBool('stop-on-parser-error', Options.StopOnParseError);
   AddBool('parse-impl', Options.InterfaceOnly);
   AddBool('dont-trim', Options.DontTrim);
+  AddBool('emit-notes', Options.EmitNotes);
 end;
 
 

utils/fpdoc/mkfpdoc.pp

@@ -155,6 +155,7 @@ begin
       If FVerbose then
         DoLog('Writing documentation');
       OnLog:=Self.OnLog;
+      EmitNotes:=Options.EmitNotes;
       If Options.BackendOptions.Count>0 then
         for I:=0 to ((Options.BackendOptions.Count-1) div 2) do
           begin

utils/fpdoc/testunit.pp

@@ -21,7 +21,7 @@ Type
   TAnEnumType         = (one,two,three);
   TASetType           = Set of TAnEnumType;
   TAnArrayType        = Array[1..10] of Integer;
-  TASubRangeType      = one..two;
+//  TASubRangeType      = one..two;
   TABooleanArrayType  = Array[Boolean] of Integer;  
   TARecordType        = Record
                          X,Y : Integer;

utils/fpdoc/testunit.xml

@@ -12,6 +12,9 @@
 <short></short>
 <descr>
 </descr>
+<notes>
+  <note>Unit note</note>
+</notes>
 
 <!-- constant Visibility: default -->
 <element name="AnIntegerConst">
@@ -107,6 +110,9 @@ Appears in 2.0
 </version>
 <seealso>
 </seealso>
+<notes>
+<note>Type note 1</note>
+</notes>
 </element>
 
 <!-- enumeration value Visibility: default -->
@@ -427,6 +433,9 @@ Appears in 2.0
 </version>
 <seealso>
 </seealso>
+<notes>
+<note>Simpleproc note 1</note>
+</notes>
 </element>
 
 <!-- procedure Visibility: default -->
@@ -1013,6 +1022,9 @@ Appears in 2.0
 </errors>
 <seealso>
 </seealso>
+<notes>
+<note> this is class note 1</note>
+</notes>
 </element>
 
 <!-- procedure Visibility: public -->
@@ -1035,6 +1047,9 @@ Appears in 2.0
 </errors>
 <seealso>
 </seealso>
+<notes>
+<note> this is proc note 1</note>
+</notes>
 </element>
 
 <!-- property Visibility: published -->
@@ -1044,6 +1059,10 @@ Appears in 2.0
 </descr>
 <seealso>
 </seealso>
+<notes>
+<note> this is prop note 1</note>
+<note> this is prop note 2</note>
+</notes>
 </element>
 
 </module> <!-- testunit -->