uichtmldoc.pas

DelphiDoc is a program for automatic generation of documentation on a Delphi-Project. At the momen

end;

{Called for each node representing a topic in the documentation of classes
 (record-like types).
~param Node          the node representing a topic
~param VisitChildren out: whether the children of the node (the content) should
                          also be visited; default is True }
procedure TICSummaryVisitor.TopicCommentClass(Node: TICNTopicForClass;
                                              var VisitChildren: Boolean);
begin
 Stop;                                    //sentence ended
 VisitChildren := False;
end;


{Called for each node representing the list of parameters of a function or
 function type as a dictionary.
~param Node          the node representing the list of parameters
~param VisitChildren out: whether the children of the node (the parameters
                          and their descriptions) should also be visited;
                          default is True }
procedure TICSummaryVisitor.ParameterList(Node: TICNParameterlist;
                                          var VisitChildren: Boolean);
begin
 Stop;                                    //sentence ended
 VisitChildren := False;
end;

{Called for each node representing the list of exceptions raised by a
 function or functions of a function type as a dictionary.
~param Node          the node representing the list of exceptions
~param VisitChildren out: whether the children of the node (the exceptions
                     and their descriptions) should also be visited;
                     default is True }
procedure TICSummaryVisitor.ExceptionList(Node: TICNExceptionlist;
                                          var VisitChildren: Boolean);
begin
 Stop;                                    //sentence ended
 VisitChildren := False;
end;




{Called for each node representing a token in the list of ancestors of a class
 or interface.
~param Token the token in the list of ancestors }
procedure TICSummaryVisitor.AncestorListToken(Token: TICAncestorListToken);
begin
 Stop;                                    //sentence ended
end;


{Called for each node representing a token in the hierarchy of classes
 (record-like types).
~param Token the token in the class hierarchy
~param Kind  the kind of record-like type the token is for }
procedure TICSummaryVisitor.ClassListToken(Token: TICClassListToken;
                                           Kind: TRecordKind);
begin
 Stop;                                    //sentence ended
end;

















   { * * *  ***  * * *  ***   TICHTMLFilesVisitor   ***  * * *  ***  * * *  }


{Called for each node representing a topic in the documentation of identifiers
 or files as derived from its comment.
~param Node          the node representing a topic
~param VisitChildren out: whether the children of the node (the content) should
                          also be visited; default is True }
procedure TICHTMLFilesVisitor.TopicComment(Node: TICNTopicForComment;
                                         var VisitChildren: Boolean);
var       IsClassOrFile      :Boolean; //whether it is a record-like type
          IsMember           :Boolean; //whether identifier is a member
begin
 IsClassOrFile := not Assigned(FGenerator.CommentIdent) or     //is a file
                  (FGenerator.CommentIdent is TRecordType);    //or a class?
 //is a member?
 IsMember := not IsClassOrFile and Assigned(FGenerator.CommentIdent.MemberOf);
 case Node.Topic of                                 //handle the node
   ictcComment:             if not IsClassOrFile then //for sub-identifiers
                             begin
                              if IsMember then          //start its comment
                               FHTMLFile.WriteString('<dd class="member">')
                              else
                               FHTMLFile.WriteString('  <dd class="ident">');
                             end;
 end;

 inherited TopicComment(Node, VisitChildren);         //handle the topic

 case Node.Topic of
   ictcComment:             if not IsClassOrFile then //for sub-identifiers
                             begin
                              if IsMember then          //end its comment
                               FHTMLFile.WriteString('</dd>')
                              else
                               FHTMLFile.WriteString('  </dd>');
                              FHTMLFile.WriteString(FGenerator.NewLine);
                             end;
 end;
end;

{Called for each node containing the declaration of an identifier.
~param Node          the node containing the declaration of an identifier
~param VisitChildren out: whether the children of the node (the declaration)
                          should also be visited; default is True }
procedure TICHTMLFilesVisitor.IdentifierDeclaration(
                                               Node: TICNIdentifierDeclaration;
                                               var VisitChildren: Boolean);
          //the identifier whose declaration should be written
var       Ident      :TIdentifier;
          IsMember   :Boolean;             //whether identifier is a member
begin
 Ident := FGenerator.CommentIdent;         //get the identifier
 IsMember := Assigned(Ident.MemberOf);     //is a member?

 FHTMLFile.WriteString(FGenerator.NewLine);

 //start definition of the identifier with an anchor
 if IsMember then
  FHTMLFile.WriteString('<dt class="member">')
 else
  FHTMLFile.WriteString('  <dt class="ident">');

 FHTMLFile.WriteString(FGenerator.TagConstants.br);
 FHTMLFile.WriteString('<a name="I_');

 if Ident.InternalNameIndex <> 0 then
  FHTMLFile.WriteString(IntToStr(Ident.InternalNameIndex));

 FHTMLFile.WriteString(Ident.Name);

 if FGenerator.XMLConformity then          //XML only accepts the "id"
  begin
   FHTMLFile.WriteString('" id="I_');
   if Ident.InternalNameIndex <> 0 then
    FHTMLFile.WriteString(IntToStr(Ident.InternalNameIndex));
   FHTMLFile.WriteString(Ident.Name);
  end;

 FHTMLFile.WriteString('">');

 FHTMLFile.WriteString(FGenerator.GetScope(Ident.Scope)); //write its scope
 FHTMLFile.WriteString('</a>');            //for the anchor

 if IsMember then
  begin
   //if it is a property with read-only access write an indicating icon
   if (Ident is TProperty) and TProperty(Ident).IsReadOnly then
    FHTMLFile.WriteString(FGenerator.GetReadOnlyIcon);
   //if it is an abstract method, write an indicating icon
   if (Ident is TFunction) and (faAbstract in TFunction(Ident).Attributes) then
    FHTMLFile.WriteString(FGenerator.GetAbstractIcon);
  end;

 //write its portability issues
 FHTMLFile.WriteString(FGenerator.GetPortabilityIssues(Ident.Portability));

 FHTMLFile.WriteCharacter(' ');

 if not IsMember and (Ident is TType) then //if it is a simple type
  begin
   FHTMLFile.WriteString(Ident.Name);        //write the name of the identifier
   FHTMLFile.WriteString(' = ');
  end;

 VisitChildren := False;                   //write the declaration
 Node.VisitChildren(Self);

 FHTMLFile.WriteString('</dt>');           //end definition of identifier
 FHTMLFile.WriteString(FGenerator.NewLine);
end;











   { * * *  ***  * * *  ***   TICHTMLDoc   ***  * * *  ***  * * *  }


{Creates the generator object and the visitor of nodes. }
constructor TICHTMLDoc.Create;
begin
 inherited Create;                             //create the generator

 FVisitor := TICHTMLFilesVisitor.Create(Self); //create the visitor
end;


{Returns a description of the documentation of the generator.
~result a description of the documentation of the generator }
class function TICHTMLDoc.GetDescription: TGeneratorDescription;
begin
 Result.Name := 'HTML Files';
 Result.Identification := 'HTML';
 Result.Description :=
  'A lot of HyperText Markup Language (HTML)-files (*.html) will be created in the given directory along with some images (*.gif), a cascading style sheet-file (DelphiDoc.css) and some additional diagram images.' + LineDelimiter +
  'The index-file is called "index.html". Just try to open it with a browser of your choice.';
end;




{Returns the capabilities of this class of generators.
~result the capabilities of this class of generators }
class function TICHTMLDoc.Capabilities: TGeneratorCapabilities;
begin
 Result := inherited Capabilities + [gcGUIHelp];
end;










{Returns the unique ID of an identifier or file to be used in the
 documentation, for instance to create a link to it.
~param Ident   the identifier to return a link to (nil, to return a link to the
               file)
~param TheFile the file, if it is not an identifier
~result the unique ID of the identifier or file }
function TICHTMLDoc.GetURIOf(Ident: TIdentifier;
                             TheFile: TPascalFile = nil): String;
var      TheClass  :TRecordType;          //the class to link to/in
begin
 Assert(Assigned(Ident) <> Assigned(TheFile));
 Assert(not DoNotDocumentIdentifier(Ident, TheFile));

 //not a record-like type or a member?
 if not Assigned(Ident) or
    (not Assigned(Ident.MemberOf) and not (Ident is TRecordType)) then
  begin
   if Assigned(Ident) then
    TheFile := Ident.InFile;                //get the file

   Result := 'File_';                       //set file prefix
   if TheFile.InternalNameIndex <> 0 then   //add number of file
    Result := Result + IntToStr(TheFile.InternalNameIndex);
   //and add the name and extension of (X)HTML file
   Result := Result + TheFile.InternalFileName + FileExtension;
  end
 else
  Result := '';                             //no URI so far


 if Assigned(Ident) then                  //link to an identifier?
  begin
   if Ident is TRecordType then             //get the record-like type
    TheClass := TRecordType(Ident)
   else
    TheClass := Ident.MemberOf;

   if Assigned(TheClass) then               //is (in) a record-like type?
    begin
     //is not in the same HTML file or need link to its top
     if AddingDiagram or not Assigned(CommentIdent) or
        ((TheClass <> CommentIdent) and (TheClass <> CommentIdent.MemberOf)) or
        (Ident = TheClass) then
      begin

       { Record-like types and their members are in extra files. }

       Result := DescFilePreFix[TheClass.Kind] + '_'; //add type of record-like
       if TheClass.InternalNameIndex <> 0 then       //add number of identifier
        Result := Result + IntToStr(TheClass.InternalNameIndex);
       Result := Result + TheClass.Name + FileExtension; //and name + extension
      end;
    end
   else
    //is in the same (HTML) file and no link to its top needed?
    if (AddingDiagram or (Ident.InFile = CommentFile)) and
       not (CommentIdent is TRecordType) and
       (not Assigned(CommentIdent) or not Assigned(CommentIdent.MemberOf)) then
     Result := '';                                   //remove file part

   //now add the link (anchor) to the identifier in the HTML file, if needed
   if Ident <> TheClass then
    begin
     Result := Result + '#I_';                 //add identifier-anchor prefix
     if Ident.InternalNameIndex <> 0 then      //add index of the identifier
      Result := Result + IntToStr(Ident.InternalNameIndex);
     Result := Result + Ident.Name;            //and add name of the identifier
    end;
  end; //if Assigned(Ident)
end;

















{Creates a new HTML file and writes its header.
~param FileName          the name of the file to create
~param TitlePart         the title of the HTML page, already quoted for the
                         HTML format
~param KeyWords          the keywords of the HTML page in the index, quoted in
                         HTML
~param HeaderContentProc a method to be called to write additional content
                         into the header of the new HTML file
~result the stream to write to the file }
function TICHTMLDoc.CreateFile(const FileName, TitlePart, KeyWords: String;
                               HeaderContentProc: THeaderWriteProcedure
                                                  = nil): TBufferStream;
var      Title     :String;            //the title of the page
         Keys      :String;            //the list of key-words for the page
         //counter through all kinds of record-like types