paweld/fpc
1
0
Fork 0
mirror of https://gitlab.com/freepascal.org/fpc/source.git synced 2025-11-02 22:29:24 +01:00
Code Issues Packages Projects Releases Wiki Activity

* Added functionality to add (and show) notes

Browse Source 
git-svn-id: trunk@20304 -
This commit is contained in:
michael 2012-02-11 09:58:13 +00:00
parent 3b006c4a9c
commit 57647f4521
10 changed files with 123 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

7
utils/fpdoc/dglobals.pp
View File

@ -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;

18
utils/fpdoc/dw_html.pp
View File

@ -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;

8
utils/fpdoc/dwlinear.pp
View File

@ -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

67
utils/fpdoc/dwriter.pp
View File

@ -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);

2
utils/fpdoc/fpdoc.pp
View File

@ -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

2
utils/fpdoc/fpdocproj.pas
View File

@ -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 }

6
utils/fpdoc/fpdocxmlopts.pas
View File

@ -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;

1
utils/fpdoc/mkfpdoc.pp
View File

@ -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

2
utils/fpdoc/testunit.pp
View File

@ -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;

19
utils/fpdoc/testunit.xml
View File

@ -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 -->