paweld/fpc
1
0
Fork 0
mirror of https://gitlab.com/freepascal.org/fpc/source.git synced 2025-04-14 00:59:30 +02:00
Code Issues Packages Projects Releases Wiki Activity

o commit patch from Mantis 17191:

Browse Source 
* Patch with new linear based IPF writer
    * patch for Interfaces Overview in all Linear writers
    * patch with new Linear Writer specific parameter to control
      if linked documentation should be duplicated or not.
      new parameter is: --duplinkeddoc
      Default is that linked docs are not duplicated.
    * patch for fixing minor spelling mistakes in fpdoc
    * patch to not create a section Errors if there isn't actually
      any specific documentation for errors. makeskel generates error
      nodes but most don't have any items. This caused an Errors title
      in the docs, but with no content.
    * patch to fix SeeAlso section in Linear writer. It never output
      the custom text, but always the node link as text.
    * new features for linear writer that could be overridden in
      descendants.
      - marked some protected methods as virtual so it can be overridden
        in descendants for customization.
      - new section for listing Types found in a unit. Default does nothing,
        except in IPF writer.
      - new section for listing Variables found in a unit. Default does
        nothing, except in IPF writer.
      - new section for listing Constants found in a unit. Default does
        nothing, except in IPF writer.

git-svn-id: trunk@15849 -
This commit is contained in:
marco 2010-08-19 04:26:26 +00:00
parent 11654d5f8c
commit e6277f6633
9 changed files with 1218 additions and 1388 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.gitattributes vendored
View File

@ -11616,7 +11616,7 @@ utils/fpdoc/dglobals.pp svneol=native#text/plain
utils/fpdoc/dw_dxml.pp svneol=native#text/plain
utils/fpdoc/dw_html.pp svneol=native#text/plain
utils/fpdoc/dw_htmlchm.inc svneol=native#text/plain
utils/fpdoc/dw_ipf.pp svneol=native#text/plain
utils/fpdoc/dw_ipflin.pas svneol=native#text/plain
utils/fpdoc/dw_latex.pp svneol=native#text/plain
utils/fpdoc/dw_linrtf.pp svneol=native#text/plain
utils/fpdoc/dw_lintmpl.pp svneol=native#text/plain

7
utils/fpdoc/dglobals.pp
View File

@ -63,6 +63,7 @@ resourcestring
SDocRemark = 'Remark: ';
SDocMethodOverview = 'Method overview';
SDocPropertyOverview = 'Property overview';
SDocInterfacesOverview = 'Interfaces overview';
SDocPage = 'Page';
SDocMethod = 'Method';
SDocProperty = 'Property';
@ -119,6 +120,10 @@ resourcestring
SCHMUsageAutoIDX = 'Automatically generate an Index. Ignores --index-file';
SCHMUsageMakeSearch = 'Automatically generate a Search Index from filenames that match *.htm*';
// Linear usage
SLinearUsageDupLinkedDocsP1 = 'Duplicate linked element documentation in';
SLinearUsageDupLinkedDocsP2 = 'descendant classes.';
STitle = 'FPDoc - Free Pascal Documentation Tool';
SVersion = 'Version %s [%s]';
SCopyright = '(c) 2000 - 2003 Areca Systems GmbH / Sebastian Guenther, sg@freepascal.org';
@ -155,7 +160,7 @@ resourcestring
SDone = 'Done.';
SErrCouldNotCreateOutputDir = 'Could not create output directory "%s"';
SErrCouldNotCreateFile = 'Could not create file "%s": %s';
SSeeURL = '(See %s)'; // For lineair text writers.
SSeeURL = '(See %s)'; // For linear text writers.
Const
SVisibility: array[TPasMemberVisibility] of string =

1341
utils/fpdoc/dw_ipf.pp
View File

File diff suppressed because it is too large Load Diff

1010
utils/fpdoc/dw_ipflin.pas Normal file
View File

File diff suppressed because it is too large Load Diff

8
utils/fpdoc/dw_latex.pp
View File

@ -77,8 +77,8 @@ Type
procedure StartChapter(ChapterName : String); override;
procedure StartOverview(WithAccess : Boolean); override;
procedure EndOverview; override;
procedure WriteOverviewMember(ALabel,AName,Access,ADescr : String); override;
procedure WriteOverviewMember(ALabel,AName,ADescr : String); override;
procedure WriteOverviewMember(const ALabel,AName,Access,ADescr : String); override;
procedure WriteOverviewMember(const ALabel,AName,ADescr : String); override;
Class Function FileNameExtension : String; override;
// Description node conversion
procedure DescrBeginBold; override;
@ -658,13 +658,13 @@ begin
WriteLn('\end{tabularx}');
end;
procedure TLatexWriter.WriteOverviewMember(ALabel,AName,Access,ADescr : String);
procedure TLatexWriter.WriteOverviewMember(const ALabel,AName,Access,ADescr : String);
begin
WriteLnF('\pageref{%s} & %s & %s & %s \\',[ALabel,EscapeText(AName),Access,ADescr]);
end;
procedure TLatexWriter.WriteOverviewMember(ALabel,AName,ADescr : String);
procedure TLatexWriter.WriteOverviewMember(const ALabel,AName,ADescr : String);
begin
WriteLnF('\pageref{%s} & %s & %s \\',[ALabel,EscapeText(AName),ADescr]);

8
utils/fpdoc/dw_linrtf.pp
View File

@ -111,8 +111,8 @@ type
procedure StartSubSubSection(SubSubSectionName : String);override;
procedure StartChapter(ChapterName : String); override;
procedure StartOverview(WithAccess : Boolean); override;
procedure WriteOverviewMember(ALabel,AName,Access,ADescr : String); override;
procedure WriteOverviewMember(ALabel,AName,ADescr : String); override;
procedure WriteOverviewMember(const ALabel,AName,Access,ADescr : String); override;
procedure WriteOverviewMember(const ALabel,AName,ADescr : String); override;
procedure EndOverview; override;
Class Function FileNameExtension : String; override;
// Description node conversion
@ -714,7 +714,7 @@ begin
[EscapeText(SDocPage), EscapeText(SDocProperty), EscapeText(SDocDescription)]);
end;
procedure TRTFWriter.WriteOverviewMember(ALabel,AName,Access,ADescr : String);
procedure TRTFWriter.WriteOverviewMember(const ALabel,AName,Access,ADescr : String);
begin
//TODO: Translate Latex \pageref to RTF
//WriteLnF('\pageref{%s} & %s & %s & %s \\',[ALabel,AName,Access,ADescr]);
@ -722,7 +722,7 @@ begin
[ALabel,AName,Access,ADescr]);
end;
procedure TRTFWriter.WriteOverviewMember(ALabel,AName,ADescr : String);
procedure TRTFWriter.WriteOverviewMember(const ALabel,AName,ADescr : String);
begin
//TODO: Translate Latex \pageref to RTF
//WriteLnF('\pageref{%s} & %s & %s \\',[ALabel,AName,ADescr]);

8
utils/fpdoc/dw_txt.pp
View File

@ -80,8 +80,8 @@ Type
procedure StartChapter(ChapterName : String); override;
procedure StartOverview(WithAccess : Boolean); override;
procedure EndOverview; override;
procedure WriteOverviewMember(ALabel,AName,Access,ADescr : String); override;
procedure WriteOverviewMember(ALabel,AName,ADescr : String); override;
procedure WriteOverviewMember(const ALabel,AName,Access,ADescr : String); override;
procedure WriteOverviewMember(const ALabel,AName,ADescr : String); override;
Class Function FileNameExtension : String; override;
// Description node conversion
procedure DescrBeginBold; override;
@ -637,13 +637,13 @@ begin
WriteLine(False);
end;
procedure TTxtWriter.WriteOverviewMember(ALabel,AName,Access,ADescr : String);
procedure TTxtWriter.WriteOverviewMember(const ALabel,AName,Access,ADescr : String);
begin
WriteLnF('%.30s %.10s %s',[AName,Access,ADescr]);
end;
procedure TTxtWriter.WriteOverviewMember(ALabel,AName,ADescr : String);
procedure TTxtWriter.WriteOverviewMember(const ALabel,AName,ADescr : String);
begin
WriteLnF('%.30s %s ',[AName,ADescr]);

218
utils/fpdoc/dwlinear.pp
View File

@ -14,19 +14,23 @@ Type
FStream : TStream;
PackageName: String;
Module: TPasModule;
ModuleName: String;
FLastURL : DomString;
private
FDupLinkedDoc: Boolean;
Protected
ModuleName: String;
// Writing support.
procedure Write(const s: String); virtual;
procedure WriteLn(const s: String); virtual;
procedure WriteF(const s: String; const Args: array of const);
procedure WriteLnF(const s: String; const Args: array of const);
procedure WriteF(const s: String; const Args: array of const); virtual;
procedure WriteLnF(const s: String; const Args: array of const); virtual;
Function PushWriteContext(S : TStream) : TStream;
Procedure PopWriteContext(S : TSTream);
procedure WriteLabel(El: TPasElement);
procedure WriteIndex(El: TPasElement);
procedure WriteTypeDecl(El: TPasElement); virtual;
procedure WriteVariableDecl(El: TPasElement); virtual;
procedure WriteConstDecl(El: TPasElement); virtual;
// Auxiliary routines
procedure DescrBeginURL(const AURL: DOMString); override; // Provides a default implementation
procedure DescrEndURL; override;
@ -64,6 +68,9 @@ Type
function GetLabel(AElement: TPasElement): String; virtual; abstract;
procedure WriteLabel(Const S : String); virtual; abstract;
procedure WriteIndex(Const S : String); virtual; abstract;
procedure WriteType(const s: string); virtual;
procedure WriteVariable(const s: string); virtual;
procedure WriteConstant(const s: string); virtual;
procedure StartChapter(ChapterName : String); virtual; abstract;
procedure StartSection(SectionName : String); virtual; abstract;
procedure StartSubSection(SubSectionName : String); virtual; abstract;
@ -73,8 +80,8 @@ Type
Procedure WriteExampleFile(FN : String); virtual; abstract;
procedure StartOverview(WithAccess : Boolean); virtual; Abstract;
procedure EndOverview; virtual; Abstract;
procedure WriteOverviewMember(ALabel,AName,Access,ADescr : String); virtual; Abstract;
procedure WriteOverviewMember(ALabel,AName,ADescr : String); virtual; Abstract;
procedure WriteOverviewMember(const ALabel,AName,Access,ADescr : String); virtual; Abstract;
procedure WriteOverviewMember(const ALabel,AName,ADescr : String); virtual; Abstract;
procedure StartUnitOverview(AModuleName,AModuleLabel : String);virtual; Abstract;
procedure WriteUnitEntry(UnitRef : TPasType);virtual; Abstract;
procedure EndUnitOverview; virtual; Abstract;
@ -82,6 +89,8 @@ Type
Property LastURL : DomString Read FLastURL Write FLastURL;
Public
Constructor Create(APackage: TPasPackage; AEngine: TFPDocEngine); override;
function InterpretOption(const Cmd, Arg: String): Boolean; override;
class procedure Usage(List: TStrings); override;
procedure WriteDoc; override;
// Linear Documentation writing methods.
Procedure ProcessPackage;
@ -90,7 +99,7 @@ Type
procedure WriteUnitOverview(ASection: TPasSection);
procedure WriteVarsConstsTypes(ASection: TPasSection);
procedure WriteConsts(ASection: TPasSection);
procedure WriteTypes(ASection: TPasSection);
procedure WriteTypes(ASection: TPasSection); virtual;
procedure WriteEnumElements(TypeDecl : TPasEnumType);
procedure WriteVars(ASection: TPasSection);
procedure WriteFunctionsAndProcedures(ASection: TPasSection);
@ -99,6 +108,7 @@ Type
procedure WriteClassDecl(ClassDecl: TPasClassType);
procedure WriteClassMethodOverview(ClassDecl: TPasClassType);
procedure WriteClassPropertyOverview(ClassDecl: TPasClassType);
procedure WriteClassInterfacesOverView(ClassDecl: TPasClassType);
procedure WriteProperty(PropDecl: TPasProperty);
procedure WriteExample(ADocNode: TDocNode);
procedure WriteSeeAlso(ADocNode: TDocNode);
@ -109,6 +119,9 @@ Type
implementation
const
cDupLinkedDocParam = '--duplinkeddoc';
{ TLinearWriter }
{ ---------------------------------------------------------------------
@ -157,9 +170,8 @@ begin
end;
procedure TLinearWriter.DescrWriteText(const AText: DOMString);
begin
self.Write(EscapeText(AText));
Write(EscapeText(AText));
end;
Function TLinearWriter.GetDescrString(AContext: TPasElement; DescrNode: TDOMElement) : String;
@ -201,6 +213,21 @@ begin
WriteIndex(EL.Name);
end;
procedure TLinearWriter.WriteTypeDecl(El: TPasElement);
begin
WriteType(El.Name);
end;
procedure TLinearWriter.WriteVariableDecl(El: TPasElement);
begin
WriteVariable(El.Name);
end;
procedure TLinearWriter.WriteConstDecl(El: TPasElement);
begin
WriteConstant(El.Name);
end;
procedure TLinearWriter.DescrBeginURL(const AURL: DOMString);
begin
FLastURL:=AURL;
@ -346,6 +373,20 @@ begin
Writeln('');
end;
procedure TLinearWriter.WriteType(const s: string);
begin
// do nothing
end;
procedure TLinearWriter.WriteVariable(const s: string);
begin
// do nothing
end;
procedure TLinearWriter.WriteConstant(const s: string);
begin
// do nothing
end;
procedure TLinearWriter.WriteClassDecl(ClassDecl: TPasClassType);
var
@ -368,8 +409,14 @@ begin
StartSubSection(SDocVersion);
WriteDescr(ClassDecl,DocNode.Version);
end;
if Assigned(DocNode.SeeAlso) then
begin
WriteSeeAlso(DocNode);
end;
end;
// Write Interfaces Overview;
WriteClassInterfacesOverView(ClassDecl);
// Write method overview
WriteClassMethodOverView(ClassDecl);
// Write Property Overview;
@ -413,7 +460,7 @@ var
L,N,S,A: String;
DocNode: TDocNode;
List : TStringList;
lNode: TDocNode;
begin
// Write property overview
List:=TStringList.Create;
@ -437,10 +484,20 @@ begin
L:=StripText(GetLabel(Member));
N:=EscapeText(Member.Name);
DocNode := Engine.FindDocNode(Member);
If Assigned(DocNode) then
S:=GetDescrString(Member, DocNode.ShortDescr)
if Assigned(DocNode) then
begin
if FDupLinkedDoc and (DocNode.Link <> '') then
begin
lNode := Engine.FindLinkedNode(DocNode);
if not Assigned(lNode) then
lNode := DocNode;
end
else
lNode := DocNode;
S := GetDescrString(Member, lNode.ShortDescr);
end
else
S:='';
S := '';
A:='';
if Length(TPasProperty(Member).ReadAccessorName) > 0 then
@ -450,6 +507,7 @@ begin
if Length(TPasProperty(Member).StoredAccessorName) > 0 then
a := a + 's';
WriteOverviewMember(L,N,A,S);
S := '';
end;
EndOverview;
end;
@ -459,6 +517,61 @@ begin
end;
procedure TLinearWriter.WriteClassInterfacesOverView(ClassDecl: TPasClassType);
var
lInterface: TPasElement;
i: Integer;
L,N,S,A: String;
DocNode: TDocNode;
List : TStringList;
lNode: TDocNode;
begin
// Write Interfaces overview
List:=TStringList.Create;
try
List.Sorted:=True;
for i := 0 to ClassDecl.Interfaces.Count-1 do
begin
lInterface := TPasElement(ClassDecl.Interfaces[i]);
List.AddObject(lInterface.Name,lInterface);
end;
if (List.Count>0) then
begin
StartSubSection(SDocInterfacesOverview);
WriteLabel(GetLabel(ClassDecl) + ':Interfaces');
StartOverView(False);
for i := 0 to List.Count-1 do
begin
lInterface := TPasElement(List.Objects[i]);
L := StripText(GetLabel(lInterface));
N := EscapeText(lInterface.Name);
DocNode := Engine.FindDocNode(lInterface);
if Assigned(DocNode) then
begin
if FDupLinkedDoc and (DocNode.Link <> '') then
begin
lNode := Engine.FindLinkedNode(DocNode);
if not Assigned(lNode) then
lNode := DocNode;
end
else
lNode := DocNode;
S := GetDescrString(lInterface, lNode.ShortDescr);
end
else
S := '';
WriteOverviewMember(L,N,S);
S := '';
end;
EndOverview;
end;
finally
List.Free;
end;
end;
function TLinearWriter.ConstValue(ConstDecl: TPasConst): String;
begin
if Assigned(ConstDecl) then
@ -562,7 +675,7 @@ begin
begin
ResStrDecl := TPasResString(ASection.ResStrings[i]);
StartListing(false, '');
Writeln(ResStrDecl.GetDeclaration(True));
DescrWriteText(ResStrDecl.GetDeclaration(True)); // instead of WriteLn() so we can do further processing like manual line wrapping in descendants
EndListing;
WriteLabel(ResStrDecl);
WriteIndex(ResStrDecl);
@ -683,6 +796,7 @@ begin
begin
DescrBeginParaGraph;
ConstDecl := TPasConst(ASection.Consts[i]);
WriteConstDecl(ConstDecl);
StartListing(False,'');
WriteLn(EscapeText(ConstDecl.GetDeclaration(True)));
EndListing;
@ -746,16 +860,19 @@ begin
StartSubSection(SDocTypes,ModuleName+'Types');
for i := 0 to ASection.Types.Count - 1 do
begin
DescrBeginParaGraph;
DescrBeginParagraph;
TypeDecl := TPasType(ASection.Types[i]);
WriteTypeDecl(TypeDecl);
StartListing(False,'');
DocNode := Engine.FindDocNode(TypeDecl);
If Assigned(DocNode) and
Assigned(DocNode.Node) and
(Docnode.Node['opaque']='1') then
Writeln(TypeDecl.Name+' = '+SDocOpaque)
else
Writeln(EscapeText(TypeDecl.GetDeclaration(True)));
else
begin
Writeln(EscapeText(TypeDecl.GetDeclaration(True)));
end;
EndListing;
WriteLabel(TypeDecl);
WriteIndex(TypeDecl);
@ -769,7 +886,7 @@ begin
Writeln(Format('%s : ',[SDocVersion]));
WriteDescr(TypeDecl, DocNode.Version);
end;
DescrEndParaGraph;
DescrEndParagraph;
end;
end;
end;
@ -788,6 +905,7 @@ begin
begin
DescrBeginParaGraph;
VarDecl := TPasVariable(ASection.Variables[i]);
WriteVariableDecl(VarDecl);
StartListing(False,'');
WriteLn(EscapeText(VarDecl.GetDeclaration(True)));
EndListing;
@ -857,7 +975,7 @@ begin
StartDescription;
WriteDescr(ProcDecl);
end;
if Assigned(DocNode.ErrorsDoc) then
if Assigned(DocNode.ErrorsDoc) and (DocNode.ErrorsDoc.HasChildNodes) then
begin
StartErrors;
WriteDescr(ProcDecl, DocNode.ErrorsDoc);
@ -920,6 +1038,7 @@ procedure TLinearWriter.WriteProperty(PropDecl : TPasProperty);
var
DocNode: TDocNode;
S: String;
lNode: TDocNode;
begin
With PropDecl do
begin
@ -928,11 +1047,23 @@ begin
WriteIndex(Parent.Name+'.'+Name);
StartProperty;
DocNode := Engine.FindDocNode(PropDecl);
if Assigned(DocNode) and Assigned(DocNode.ShortDescr) then
if Assigned(DocNode) then
begin
if FDupLinkedDoc and (DocNode.Link <> '') then
begin
StartSynopsis;
WriteDescr(PropDecl, DocNode.ShortDescr);
lNode := Engine.FindLinkedNode(DocNode);
if not Assigned(lNode) then
lNode := DocNode;
end
else
lNode := DocNode;
if Assigned(lNode.ShortDescr) then
begin
StartSynopsis;
WriteDescr(PropDecl, lNode.ShortDescr);
end;
end;
StartDeclaration;
StartListing(False);
WriteLn('Property '+GetDeclaration(True));
@ -954,27 +1085,27 @@ begin
end;
Writeln(S);
if Assigned(DocNode) then
begin
if Assigned(DocNode.Descr) then
begin
if Assigned(lNode.Descr) then // lNode will be assigned if DocNode exists
begin
StartDescription;
WriteDescr(PropDecl);
WriteDescr(PropDecl, lNode);
end;
if Assigned(DocNode.ErrorsDoc) then
if Assigned(lNode.ErrorsDoc) and (lNode.ErrorsDoc.HasChildNodes) then
begin
StartErrors;
WriteDescr(PropDecl, DocNode.ErrorsDoc);
end;
if Assigned(DocNode.Version) then
if Assigned(lNode.Version) then
begin
StartVersion;
WriteDescr(PropDecl, DocNode.Version);
WriteDescr(PropDecl, lNode.Version);
end;
WriteSeeAlso(DocNode);
WriteSeeAlso(lNode);
EndProperty;
WriteExample(DocNode);
end
else
WriteExample(lNode);
end
else
EndProperty;
end;
end;
@ -1004,6 +1135,8 @@ begin
Writeln(',');
S:=TDomElement(Node)['id'];
DescrBeginLink(S);
if Node.FirstChild <> nil then
s := Node.FirstChild.NodeValue;
Write(EscapeText(S));
DescrEndLink();
end;
@ -1208,6 +1341,7 @@ var
i: Integer;
begin
inherited ;
FDupLinkedDoc := False; // by default we don't duplicate linked element documentation
{ Allocate labels for all elements for which we are going to create
documentation. This is needed for links to work correctly. }
@ -1231,6 +1365,28 @@ end;
procedure TLinearWriter.WriteEndDocument;
begin
// do nothing
end;
function TLinearWriter.InterpretOption(const Cmd: String; const Arg: String): Boolean;
begin
Result := True;
if Cmd = cDupLinkedDocParam then
begin
FDupLinkedDoc := True;
end
else
Result := False;
end;
class procedure TLinearWriter.Usage(List: TStrings);
begin
List.Add(cDupLinkedDocParam);
List.Add(SLinearUsageDupLinkedDocsP1);
List.Add('');
List.Add(SLinearUsageDupLinkedDocsP2);
end;
end.

4
utils/fpdoc/fpdoc.pp
View File

@ -24,9 +24,9 @@ uses
dw_XML, // XML writer
dw_dxml, // Delphi XML doc.
dw_HTML, // HTML writer
dw_ipf, // IPF writer
dw_ipflin, // IPF writer (new linear output)
dw_man, // Man page writer
dw_linrtf, // lineair RTF writer
dw_linrtf, // linear RTF writer
dw_txt; // TXT writer
const