From 576fe3758d7fdabd813ec510e3b74afdb372e69e Mon Sep 17 00:00:00 2001 From: michael Date: Thu, 6 Feb 2014 17:06:58 +0000 Subject: [PATCH] * Added showing of hints in HTML page title git-svn-id: trunk@26687 - --- utils/fpdoc/dglobals.pp | 68 ++++++++++++++++++++++++++++++++++++----- utils/fpdoc/dw_html.pp | 46 ++++++++++++++++------------ utils/fpdoc/dw_man.pp | 3 +- utils/fpdoc/dwlinear.pp | 20 +++--------- utils/fpdoc/mkfpdoc.pp | 3 ++ 5 files changed, 95 insertions(+), 45 deletions(-) diff --git a/utils/fpdoc/dglobals.pp b/utils/fpdoc/dglobals.pp index 4e1a7167a0..b1a736041d 100644 --- a/utils/fpdoc/dglobals.pp +++ b/utils/fpdoc/dglobals.pp @@ -304,6 +304,7 @@ type function ResolveLinkInPackages(AModule: TPasModule; const ALinkDest: String; Strict: Boolean=False): String; function ResolveLinkInUsedUnits(AModule: TPasModule; const ALinkDest: String; Strict: Boolean=False): String; protected + FAlwaysVisible : TStringList; DescrDocs: TObjectList; // List of XML documents DescrDocNames: TStringList; // Names of the XML documents FRootLinkNode: TLinkNode; @@ -334,12 +335,17 @@ type override; function FindElement(const AName: String): TPasElement; override; function FindModule(const AName: String): TPasModule; override; + Function HintsToStr(Hints : TPasMemberHints) : String; // Link tree support procedure AddLink(const APathName, ALinkTo: String); function FindAbsoluteLink(const AName: String): String; function ResolveLink(AModule: TPasModule; const ALinkDest: String; Strict : Boolean = False): String; function FindLinkedNode(ANode: TDocNode): TDocNode; + Function ShowElement(El : TPasElement) : Boolean; inline; + + // Call this before documenting. + Procedure StartDocumenting; virtual; // Documentation file support procedure AddDocFile(const AFilename: String;DontTrim:boolean=false); @@ -348,8 +354,7 @@ type function FindDocNode(AElement: TPasElement): TDocNode; function FindDocNode(ARefModule: TPasModule; const AName: String): TDocNode; function FindShortDescr(AElement: TPasElement): TDOMElement; - function FindShortDescr(ARefModule: TPasModule; - const AName: String): TDOMElement; + function FindShortDescr(ARefModule: TPasModule; const AName: String): TDOMElement; function GetExampleFilename(const ExElement: TDOMElement): String; property RootLinkNode: TLinkNode read FRootLinkNode; @@ -607,6 +612,8 @@ constructor TFPDocEngine.Create; begin inherited Create; DescrDocs := TObjectList.Create; + FAlwaysVisible := TStringList.Create; + FAlwaysVisible.CaseSensitive:=True; DescrDocNames := TStringList.Create; FRootLinkNode := TLinkNode.Create('', ''); FRootDocNode := TDocNode.Create('', nil); @@ -621,10 +628,11 @@ var begin for i := 0 to FPackages.Count - 1 do TPasPackage(FPackages[i]).Release; - FRootDocNode.Free; - FRootLinkNode.Free; - DescrDocNames.Free; - DescrDocs.Free; + FreeAndNil(FRootDocNode); + FreeAndNil(FRootLinkNode); + FreeAndNil(DescrDocNames); + FreeAndNil(DescrDocs); + FreeAndNil(FAlwaysVisible); inherited Destroy; end; @@ -1224,7 +1232,24 @@ begin end; end; -Function TFPDocEngine.ParseUsedUnit(AName,AInputLine,AOSTarget,ACPUTarget : String) : TPasModule; +function TFPDocEngine.HintsToStr(Hints: TPasMemberHints): String; + +Var + H : TPasMemberHint; + +begin + Result:=''; + For h:=Low(TPasMemberHint) to High(TPasMemberHint) do + if h in Hints then + begin + if (Result<>'') then + Result:=Result+', '; + Result:=Result+cPasMemberHint[h] + end; +end; + +function TFPDocEngine.ParseUsedUnit(AName, AInputLine, AOSTarget, + ACPUTarget: String): TPasModule; Var M : TPasModule; @@ -1359,6 +1384,9 @@ end; procedure TFPDocEngine.AddDocFile(const AFilename: String;DontTrim:boolean=false); +Var + PN : String; + function ReadNode(OwnerDocNode: TDocNode; Element: TDOMElement): TDocNode; var Subnode: TDOMNode; @@ -1369,6 +1397,8 @@ procedure TFPDocEngine.AddDocFile(const AFilename: String;DontTrim:boolean=false Result := OwnerDocNode.CreateChildren(Element['name']); Result.FNode := Element; Result.FLink := Element['link']; + if (Element['alwaysvisible'] = '1') and (Element.NodeName='element') then + FAlwaysVisible.Add(LowerCase(PN+'.'+TDocNode(OwnerDocNode).Name+'.'+Element['name'])); Result.FIsSkipped := Element['skip'] = '1'; Subnode := Element.FirstChild; while Assigned(Subnode) do @@ -1436,6 +1466,7 @@ begin begin PackageDocNode := ReadNode(RootDocNode, TDOMElement(Node)); PackageDocNode.IncRefCount; + PN:=PackageDocNode.Name; // Scan all 'module' elements within this package element Subnode := Node.FirstChild; while Assigned(Subnode) do @@ -1575,6 +1606,29 @@ begin Result:=FindDocNode(CurModule,ANode.Link); end; +function TFPDocEngine.ShowElement(El: TPasElement): Boolean; +begin + Case El.Visibility of + visStrictPrivate, + visPrivate : + Result:=Not HidePrivate; + visStrictProtected, + visProtected : + begin + Result:=Not HideProtected; + if not Result then + Result:=FAlwaysVisible.IndexOf(LowerCase(El.PathName))<>-1; + end + Else + Result:=True + end; +end; + +procedure TFPDocEngine.StartDocumenting; +begin + FAlwaysVisible.Sorted:=True; +end; + function TFPDocEngine.FindShortDescr(ARefModule: TPasModule; const AName: String): TDOMElement; diff --git a/utils/fpdoc/dw_html.pp b/utils/fpdoc/dw_html.pp index 80fb23a6b2..ff90f76089 100644 --- a/utils/fpdoc/dw_html.pp +++ b/utils/fpdoc/dw_html.pp @@ -225,7 +225,7 @@ type function AppendRecordType(CodeEl, TableEl: TDOMElement; Element: TPasRecordType; NestingLevel: Integer): TDOMElement; - procedure AppendTitle(const AText: DOMString); + procedure AppendTitle(const AText: DOMString; Hints : TPasMemberHints = []); procedure AppendMenuBar(ASubpageIndex: Integer); procedure AppendTopicMenuBar(Topic : TTopicElement); procedure AppendSourceRef(AElement: TPasElement); @@ -590,8 +590,7 @@ constructor THTMLWriter.Create(APackage: TPasPackage; AEngine: TFPDocEngine); for j := 0 to ClassEl.Members.Count - 1 do begin FPEl := TPasElement(ClassEl.Members[j]); - if ((FPEl.Visibility = visPrivate) and Engine.HidePrivate) or - ((FPEl.Visibility = visProtected) and Engine.HideProtected) then + if Not Engine.ShowElement(FPEl) then continue; DocNode := Engine.FindDocNode(FPEl); @@ -1975,10 +1974,16 @@ begin Result := CodeEl; end; -procedure THTMLWriter.AppendTitle(const AText: DOMString); +procedure THTMLWriter.AppendTitle(const AText: DOMString; Hints : TPasMemberHints = []); + +Var + T : String; begin + T:=AText; + if (Hints<>[]) then + T:=T+' ('+Engine.HintsToStr(Hints)+')'; AppendText(TitleElement, AText); - AppendText(CreateH1(BodyElement), AText); + AppendText(CreateH1(BodyElement), T); end; procedure THTMLWriter.AppendTopicMenuBar(Topic : TTopicElement); @@ -2791,7 +2796,7 @@ procedure THTMLWriter.CreateModulePageBody(AModule: TPasModule; DocNode: TDocNode; begin AppendMenuBar(0); - AppendTitle(Format(SDocUnitTitle, [AModule.Name])); + AppendTitle(Format(SDocUnitTitle, [AModule.Name]),AModule.Hints); AppendShortDescr(CreatePara(BodyElement), AModule); if AModule.InterfaceSection.UsesList.Count > 0 then @@ -2918,7 +2923,7 @@ var TableEl, CodeEl: TDOMElement; begin AppendMenuBar(-1); - AppendTitle(AConst.Name); + AppendTitle(AConst.Name,AConst.Hints); AppendShortDescr(CreatePara(BodyElement), AConst); AppendText(CreateH2(BodyElement), SDocDeclaration); AppendSourceRef(AConst); @@ -3057,7 +3062,7 @@ var Variable: TPasVariable; begin AppendMenuBar(-1); - AppendTitle(AType.Name); + AppendTitle(AType.Name,AType.Hints); AppendShortDescr(CreatePara(BodyElement), AType); AppendText(CreateH2(BodyElement), SDocDeclaration); AppendSourceRef(AType); @@ -3169,7 +3174,7 @@ var ThisNode : TPasUnresolvedTypeRef; begin AppendMenuBar(-1); - AppendTitle(AClass.Name); + AppendTitle(AClass.Name,AClass.Hints); ParaEl := CreatePara(BodyElement); AppendMemberListLink(PropertiesByInheritanceSubindex, SDocProperties); @@ -3233,8 +3238,7 @@ var ah:=ol or ((Member is TPasProcedure) and (TPasProcedure(Member).ProcType.Args.Count > 0)); if ol then Member:=TPasElement((Member as TPasOverloadedProc).Overloads[0]); - if ((MVisibility = visPrivate) and Engine.HidePrivate) or - ( (MVisibility = visProtected) and Engine.HideProtected) then + if Not Engine.ShowElement(Member) then continue; if (CurVisibility <> MVisibility) then begin @@ -3328,6 +3332,12 @@ var end else AppendText(CreateWarning(CodeEl), '<' + Member.ClassName + '>'); + if (Member.Hints<>[]) then + begin + AppendKW(CodeEl,' '+Engine.HintsToStr(Member.Hints)); + AppendText(CodeEl, ' '); + AppendSym(CodeEl, ';'); + end; end; CodeEl := CreateCode(CreatePara(CreateTD(CreateTR(TableEl)))); @@ -3435,9 +3445,7 @@ var for i := 0 to ThisClass.Members.Count - 1 do begin Member := TPasElement(ThisClass.Members[i]); - if ((Member.Visibility = visPrivate) and Engine.HidePrivate) or - ((Member.Visibility = visProtected) and Engine.HideProtected) or - not AFilter(Member) then + if Not (Engine.ShowElement(Member) and AFilter(Member)) then continue; TREl := CreateTR(TableEl); ParaEl := CreatePara(CreateTD(TREl)); @@ -3488,9 +3496,7 @@ var for i := 0 to ThisClass.Members.Count - 1 do begin Member := TPasElement(ThisClass.Members[i]); - if (not (((Member.Visibility = visPrivate) and Engine.HidePrivate) or - ((Member.Visibility = visProtected) and Engine.HideProtected))) and - AFilter(Member) then + if Engine.ShowElement(Member) and AFilter(Member) then begin j := 0; while (j < List.Count) and @@ -3688,7 +3694,7 @@ var DocNode: TDocNode; begin AppendMenuBar(-1); - AppendTitle(AElement.FullName); + AppendTitle(AElement.FullName,AElement.Hints); AppendShortDescr(CreatePara(BodyElement), AElement); AppendText(CreateH2(BodyElement), SDocDeclaration); AppendSourceRef(AElement); @@ -3727,7 +3733,7 @@ var DocNode: TDocNode; begin AppendMenuBar(-1); - AppendTitle(AVar.FullName); + AppendTitle(AVar.FullName,AVar.Hints); AppendShortDescr(CreatePara(BodyElement), AVar); AppendText(CreateH2(BodyElement), SDocDeclaration); AppendSourceRef(AVar); @@ -3758,7 +3764,7 @@ var TableEl, TREl, TDEl, CodeEl: TDOMElement; begin AppendMenuBar(-1); - AppendTitle(AProc.Name); + AppendTitle(AProc.Name,AProc.Hints); AppendShortDescr(CreatePara(BodyElement), AProc); AppendText(CreateH2(BodyElement), SDocDeclaration); AppendSourceRef(AProc); diff --git a/utils/fpdoc/dw_man.pp b/utils/fpdoc/dw_man.pp index 5d051cd410..c548fd908c 100644 --- a/utils/fpdoc/dw_man.pp +++ b/utils/fpdoc/dw_man.pp @@ -262,8 +262,7 @@ constructor TManWriter.Create(APackage: TPasPackage; AEngine: TFPDocEngine); for j := 0 to ClassEl.Members.Count - 1 do begin FPEl := TPasElement(ClassEl.Members[j]); - if ((FPEl.Visibility = visPrivate) and Engine.HidePrivate) or - ((FPEl.Visibility = visProtected) and Engine.HideProtected) then + if Not Engine.ShowElement(FPEl) then continue; DocNode := Engine.FindDocNode(FPEl); diff --git a/utils/fpdoc/dwlinear.pp b/utils/fpdoc/dwlinear.pp index 6c877ff349..988fe82a0b 100644 --- a/utils/fpdoc/dwlinear.pp +++ b/utils/fpdoc/dwlinear.pp @@ -391,7 +391,6 @@ end; procedure TLinearWriter.WriteClassDecl(ClassDecl: TPasClassType); var DocNode: TDocNode; - Vis: TPasMemberVisibilities; Member: TPasElement; i: Integer; begin @@ -431,17 +430,10 @@ begin // Determine visibilities - Vis := AllVisibilities; - if Engine.HidePrivate then - Exclude(Vis,visPrivate); - if Engine.HideProtected then - Exclude(Vis,visProtected); - for i := 0 to ClassDecl.Members.Count - 1 do begin Member := TPasElement(ClassDecl.Members[i]); - if ((Member.InheritsFrom(TPasProcedureBase)) and - (Member.Visibility in Vis)) then + if Member.InheritsFrom(TPasProcedureBase) and Engine.ShowElement(Member) then WriteProcedure(TPasProcedureBase(Member)); end; @@ -450,8 +442,7 @@ begin for i := 0 to ClassDecl.Members.Count - 1 do begin Member := TPasElement(ClassDecl.Members[i]); - if ((Member.InheritsFrom(TPasProperty)) and - (Member.Visibility in Vis)) then + if Member.InheritsFrom(TPasProperty) and Engine.ShowElement(Member) then WriteProperty(TPasProperty(Member)); end; end; @@ -1184,9 +1175,7 @@ end; Function TLinearWriter.ShowMember(M : TPasElement) : boolean; begin - Result:=not ((M.Visibility=visPrivate) and Engine.HidePrivate); - If Result then - Result:=Not ((M.Visibility=visProtected) and Engine.HideProtected) + Result:=Engine.ShowElement(M); end; procedure TLinearWriter.WriteClasses(ASection: TPasSection); @@ -1320,8 +1309,7 @@ constructor TLinearWriter.Create(APackage: TPasPackage; AEngine: TFPDocEngine); for j := 0 to ClassEl.Members.Count - 1 do begin FPEl := TPasElement(ClassEl.Members[j]); - if ((FPEl.Visibility = visPrivate) and Engine.HidePrivate) or - ((FPEl.Visibility = visProtected) and Engine.HideProtected) then + if Not Engine.ShowElement(FPEl) then continue; DocNode := Engine.FindDocNode(FPEl); diff --git a/utils/fpdoc/mkfpdoc.pp b/utils/fpdoc/mkfpdoc.pp index 1a059f116d..9baa262ff7 100644 --- a/utils/fpdoc/mkfpdoc.pp +++ b/utils/fpdoc/mkfpdoc.pp @@ -228,7 +228,10 @@ begin DoLog('%s(%d,%d): %s',[e.Filename, e.Row, e.Column, e.Message]); end; if Not ParseOnly then + begin + Engine.StartDocumenting; CreateOutput(APackage,Engine); + end; finally FreeAndNil(Engine); FCurPackage:=Nil;