uichtmldoc.pas

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

~param F         the file to write the list to
~param AFile     the file whose identifiers should be written
~param WriteType the kind of identifiers to be written }
procedure TICHTMLDoc.WriteVarConstFuncsList(F: TBufferStream;
                                            AFile: TPascalFile;
                                            WriteType: TWriteKind);
var       AClass    :TIdentifierClass;    //the class of the identifiers to get

 {Gets the list of the identifiers to be written.
 ~param Scope the scope the identifier has to be in
 ~param List  the list to add the identifiers to }
 procedure GetList(Scope: TScope; List: TIdentifierList);
 var       i      :Integer;       //counter through the identifiers of the file
           Ident  :TIdentifier;   //each identifier
 begin
  for i := 0 to AFile.Idents.Count - 1 do //for each identifier
   begin
    Ident := AFile.Idents[i];               //get it
    //is of the right kind?
    if (((Ident is AClass) and
       //but not a record-like type?
         ((WriteType <> wkSimpleType) or not (Ident is TRecordType)) and
       //and also correctly a threat-variable or not?
         (not (WriteType in [wkVar, wkThreadVar]) or
          (TVariable(Ident).IsThreadVar = (WriteType = wkThreadVar)))) or
       //or enumeration item and all constants are wanted?
        ((WriteType = wkConst) and (Ident is TEnumTypeItem))) and
       //and has the right scope and is documented?
       (Ident.Scope = Scope) and not DoNotDocumentIdentifier(Ident) then
     List.AddIdent(Ident);                    //add the identifier to the list
   end;
 end;

 {Writes a list of identifiers (not functions).
 ~param List the list to be written }
 procedure WriteList(List: TIdentifierList);
 var       i        :Integer;     //counter through all identifiers
           Ident    :TIdentifier; //each identifier
 begin
  if not List.IsEmpty then        //if the list is not empty
   begin
    List.Sort;                      //sort it
    for i := 0 to List.Count - 1 do //for each identifier
     begin
      Ident := List[i];               //get it
      if i <> 0 then                  //if not the first
       F.WriteString(', ');             //add spearator

      F.WriteString('<a href="#I_');  //write (local) link to it
      if Ident.InternalNameIndex <> 0 then
        F.WriteString(IntToStr(Ident.InternalNameIndex));
      F.WriteString(Ident.Name);
      F.WriteString('">');
      F.WriteString(Ident.Name);
      F.WriteString('</a>');
     end;
   end
  else
   begin
    F.WriteString('<em>');          //write the empty list
    F.WriteString(Localize(dtDocumentationEmptyList));
    F.WriteString('</em>');
   end;
  F.WriteString(TagConstants.br); //and end the line
 end;


var       List      :TIdentifierList;    //list of identifiers in interface
          ImplList  :TIdentifierList;    //list of them in implementation part
begin
 AClass := DeclTypeClass[WriteType];     //get class of identifiers
 List := TIdentifierList.Create;         //create interface list
 try
   //interface should be documented?
   if not (fsInterface in FilterIdentifiersByScope) then
    GetList(sInterface, List);             //get identifiers in interface

   ImplList := TIdentifierList.Create;   //create implementation list
   try
     if not NoPrivateOnlyInterface and   //implementation should be documented?
        ((AFile.FileType <> sftUnit) or
         not (fsImplementation in FilterIdentifiersByScope)) and
        ((AFile.FileType = sftUnit) or    //or programs?
         not (fsProgram in FilterIdentifiersByScope)) then
      GetList(sImplementation, ImplList);  //get the identifiers

     if not List.IsEmpty or not ImplList.IsEmpty then //identifiers found?
      begin
       //write the header of the kind of identifiers
       F.WriteString('<h2 class="identslist">');
       F.WriteString(Localize(dtDocumentationFileDeclarationsHeaderPrefix));
       F.WriteString(Localize(DeclName[WriteType]));
       F.WriteString(':</h2>');
       F.WriteString(NewLine);

       //write header for identifiers in the interface part
       F.WriteString('  <b class="identsscope">');
       F.WriteString(Localize(
                           dtDocumentationFileDeclarationsHeaderGlobalPrefix));
       F.WriteString(Localize(DeclName[WriteType]));
       F.WriteString(':</b> ');
       if WriteType <> wkFunc then         //and write the list
        WriteList(List)
       else
        if List.IsEmpty then               //list is empty?
         begin
          F.WriteString('<em>');             //write the empty list
          F.WriteString(Localize(
                            dtDocumentationFileDeclarationsHeaderLocalPrefix));
          F.WriteString(Localize(dtDocumentationEmptyList));
          F.WriteString('</em>');
          F.WriteString(TagConstants.br);
         end
        else
         ShowFunctionList(F, List);          //write the list

       //identifiers in the implementation part should be documented?
       if not NoPrivateOnlyInterface and
          ((AFile.FileType <> sftUnit) or
           not (fsImplementation in FilterIdentifiersByScope)) and
          ((AFile.FileType = sftUnit) or    //or of programs?
           not (fsProgram in FilterIdentifiersByScope)) then
        begin
         //write header for identifiers in the implementation part
         F.WriteString('  <b class="identsscope">');
         F.WriteString(Localize(
                            dtDocumentationFileDeclarationsHeaderLocalPrefix));
         F.WriteString(Localize(DeclName[WriteType]));
         F.WriteString(':</b> ');
         if WriteType <> wkFunc then         //and write the list
          WriteList(ImplList)
         else
          if ImplList.IsEmpty then             //list is empty?
           begin
            F.WriteString('<em>');               //write the empty list
            F.WriteString(Localize(dtDocumentationEmptyList));
            F.WriteString('</em>');
            F.WriteString(TagConstants.br);
           end
          else
           ShowFunctionList(F, ImplList);        //write the list
        end;

       //end the section of this kind of identifiers
       F.WriteString(TagConstants.hr);
      end;
   finally
    ImplList.RemoveAll(False); //free the lists (without identifiers)
    ImplList.Free;
   end;
 finally
  List.RemoveAll(False);
  List.Free;
 end;
end;

{Writes a short, linked list of the record-like types in the file.
~param F     the file to write the list to
~param AFile the file whose record-like types should be written
~param Kind  the kind of record-like types to be written }
procedure TICHTMLDoc.WriteRecordTypeList(F: TBufferStream; AFile: TPascalFile;
                                         Kind: TRecordKind);

 {Gets the list of the record-like types of that kind to be written.
 ~param Scope the scope the type has to be in
 ~param List  the list to add the identifiers to }
 procedure GetList(Scope: TScope; List: TIdentifierList);
 var       i      :Integer;               //counter through all identifiers
           Ident  :TIdentifier;           //each identifier
 begin
  for i := 0 to AFile.Idents.Count - 1 do //for all identifiers in the file
   begin
    Ident := AFile.Idents[i];               //get it
    //is a record-like type of the correct kind and with correct scope?
    if (Ident is TRecordType) and (Ident.Scope = Scope) and
       (TRecordType(Ident).Kind = Kind) and
       not DoNotDocumentIdentifier(Ident) then  //documented?
     List.AddIdent(Ident);                        //add it to the list
   end;
 end;

 {Writes a linked list of record-like types.
 ~param List the list to be written }
 procedure WriteList(List: TIdentifierList);
 var       i      :Integer;               //counter through all identifiers
           Ident  :TIdentifier;           //each identifier
 begin
  if not List.IsEmpty then                //if the list is not empty
   begin
    List.Sort;                              //sort it
    for i := 0 to List.Count - 1 do         //for each identifier in the list
     begin
      Ident := List[i];                       //get the identifier
      if i <> 0 then                          //if not the first one
       F.WriteString(', ');                     //write a separator
      //write a link to the record-like type
      F.WriteString(GetIdentNameLink(Ident));
     end;
   end
  else
   begin
    F.WriteString('<em>');                  //write the empty list
    F.WriteString(Localize(dtDocumentationEmptyList));
    F.WriteString('</em>');
   end;
  F.WriteString(TagConstants.br);         //end the current line
 end;


var       List      :TIdentifierList;    //list of identifiers in interface
          ImplList  :TIdentifierList;    //list of them in implementation part
begin
 List := TIdentifierList.Create;         //create interface list
 try
   //interface should be documented?
   if not (fsInterface in FilterIdentifiersByScope) then
    GetList(sInterface, List);             //get the list of the identifiers

   ImplList := TIdentifierList.Create;   //create implementation list
   try
     if not NoPrivateOnlyInterface and   //implementation should be documented?
        ((AFile.FileType <> sftUnit) or
         not (fsImplementation in FilterIdentifiersByScope)) and
        ((AFile.FileType = sftUnit) or    //or programs?
         not (fsProgram in FilterIdentifiersByScope)) then
      GetList(sImplementation, ImplList);  //get the identifiers

     if not List.IsEmpty or not ImplList.IsEmpty then //identifiers found?
      begin
       //write the header of the kind of record-like types
       F.WriteString('<h2 class="identslist">');
       F.WriteString(Localize(dtDocumentationFileDeclarationsHeaderPrefix));
       F.WriteString(Localize(Plurals[Kind]));
       F.WriteString(':</h2>');
       F.WriteString(NewLine);

       //write header for record-like types in the interface part
       F.WriteString('  <b class="identsscope">');
       F.WriteString(Localize(
                           dtDocumentationFileDeclarationsHeaderGlobalPrefix));
       F.WriteString(Localize(Plurals[Kind]));
       F.WriteString(':</b> ');

       WriteList(List);                      //write the list

       //identifiers in the implementation part should be documented?
       if not NoPrivateOnlyInterface and
          ((AFile.FileType <> sftUnit) or
           not (fsImplementation in FilterIdentifiersByScope)) and
          ((AFile.FileType = sftUnit) or    //or programs?
           not (fsProgram in FilterIdentifiersByScope)) then
        begin
         //write header for record-like types in the implementation part
         F.WriteString('  <b class="identsscope">');
         F.WriteString(Localize(
                            dtDocumentationFileDeclarationsHeaderLocalPrefix));
         F.WriteString(Localize(Plurals[Kind]));
         F.WriteString(':</b> ');
         WriteList(ImplList);                  //and write the list
        end;

       //end section of this kind of record-like types
       F.WriteString(TagConstants.hr);
      end;
   finally
    ImplList.RemoveAll(False);  //free the lists (without identifiers)
    ImplList.Free;
   end;
 finally
  List.RemoveAll(False);
  List.Free;
 end;
end;




{Writes the documentation of the identifiers (of a specified kind).
~param F         the file to write the documentation to
~param List      the list of identifiers to document
~param WriteType the kind of identifiers to document }
procedure TICHTMLDoc.WriteVarConstFuncs(F: TBufferStream;
                                        List: TIdentifierList;
                                        WriteType: TWriteKind);
var       i         :Integer;           //counter through all identifiers
          Ident     :TIdentifier;       //each identifier
          Comment   :TICSimpleComment;  //the documentation of the identifier
begin
 if not List.IsEmpty then               //if the list is not empty
  begin
   List.Sort;                             //sort it

   //write the header of the documentation of the identifiers
   F.WriteString('<h2 class="idents"><a name="');
   F.WriteString(AnchorDeclName[WriteType]);
   if XMLConformity then                  //XML only accepts the "id"
    begin
     F.WriteString('" id="I_');
     F.WriteString(AnchorDeclName[WriteType]);
    end;
   F.WriteString('">');
   F.WriteString(Localize(DeclName[WriteType]));
   F.WriteString(':</a></h2>');
   F.WriteString(NewLine);

   F.WriteString('<dl class="idents">');  //start the list of identifiers
   F.WriteString(NewLine);
   for i := 0 to List.Count - 1 do        //for each identifier in the list
    begin
     Ident := List[i];                      //get it

     //set identifier for getting comment and documentation
     SetCommentIdent(Ident, Ident.InFile);
     Comment := GetFinalIdentifierComment(Ident);
     try
       WriteNode(Comment.Content, F);         //write the documentation

       //check, whether a help context was defined for this identifier
       CheckHelpContext(GetURIOf(Ident), Comment.HelpContext);
     finally
      ReleaseFinalComment(Comment);           //release the documentation
     end;
    end; //for i := 0 to List.Count - 1

   F.WriteString('</dl>');                //end list of identifiers
   F.WriteString(NewLine);
   //end documentation of kind of identifiers
   F.WriteString(TagConstants.hr);
  end; //if not List.IsEmpty
end;


{Writes the documentation about the file.
~param AFile the file whose documentation should be written }
procedure TICHTMLDoc.WriteFileDocumentation(AFile: TPascalFile);

 {Gets a list of similar identifiers to generate documentation about
 ~param List      the list to add the identifiers to
 ~param WriteType the kind of identifiers to add to the list }
 procedure GetList(List: TIdentifierList; WriteType: TWriteKind);
 var       AClass :TIdentifierClass;      //the class of the identifiers to add
           i      :Integer;               //counter through all identifiers
           Ident  :TIdentifier;           //each identifier
 begin
  List.RemoveAll(False);