* Added showing of hints in HTML page title

git-svn-id: trunk@26687 -

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;
 

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

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

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

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;