uhtmlhelpdoc.pas

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

               ListName[WriteType] + '.html">' +
               Localize(DeclName[WriteType]) + '</a>';

     StartContentList(Localize(DeclName[WriteType]));
     CreateDocumentation;          //generate documentation of all identifiers
     EndContentList;

     CreateList;                             //write list of identifiers
    end
   else
    Result := '';
 finally
  List.RemoveAll(False);             //free the list (without the identifiers)
  List.Free;
 end;
end;



{Writes a short linked list of all record-like types in the file.
~param AFile the file whose record-like types to list
~result a link to the generated list, if it is not empty }
function THTMLHelpDoc.WriteRecordTypeList(AFile: TPascalFile): String;

 {Writes a list of linked record-like types.
 ~param F    the file to write the list to
 ~param List the list to write
 ~param Kind the kind of the record-like types to be written }
 procedure WriteList(var F: TextFile; List: TIdentifierList;
                     Kind: TRecordKind);
 var       i        :Integer;            //counter through all identifiers
           Ident    :TIdentifier;        //each identifier
           None     :Boolean;        //no record-like types of this kind found?
 begin
  None := True;
  for i := 0 to List.Count - 1 do        //for each identifier in the list
   begin
    Ident := List[i];                      //get the record-like type
    if TRecordType(Ident).Kind = Kind then //is of the correct kind?
     begin
      if None then                           //is the first found one?
       begin                                   //write header
        WriteLn(F, '  <li><b>', Localize(Plurals[Kind]), '</b>');
        WriteLn(F, '    <ul>');                //start new enumeration
        None := False;
       end;
      //write a link to the record-like type
      WriteLn(F, '      <li>', GetIdentNameLink(Ident), '</li>');
     end;
   end;
  if not None then                      //record-like types of this kind found?
   begin
    WriteLn(F, '    </ul>');              //end the current enumeration
    WriteLn(F, '  </li>');
   end;
 end;


var      List        :TIdentifierList;    //list of identifiers in interface
         i           :Integer;            //counter through all identifiers
         Ident       :TIdentifier;        //each identifier
         F           :TextFile;           //the file of the list
         Kind        :TRecordKind;        //each kind of record-like types
begin
 List := TIdentifierList.Create;          //create interface list
 try
   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 and should be documented?
     if (Ident is TRecordType) and not DoNotDocumentIdentifier(Ident) then
      List.AddIdent(Ident);                    //add it to the list
    end;

   if not List.IsEmpty then               //some record-like types in the file?
    begin
     List.Sort;                             //sort the list

     //create file for the list
     CreateFile(F, GetFileName(nil, AFile) + '.recordlikes',
                DocumentationTexts[dtDocumentationFilesListsRecordLikesHeaderPrefix].T +
                ' ' + FileTypeNames[AFile.FileType] + ' ' +
                AFile.InternalFileName,
                AFile.InternalFileName + ', ' +
                Localize(dtKeyWordRecordLikeListPostfix));
     try
       WriteLn(F, '<ul>');                    //start list
       for Kind := Low(Kind) to High(Kind) do //write all record-like types
        WriteList(F, List, Kind);
       WriteLn(F, '</ul>');                   //end the list
     finally
      EndFile(F);                           //close the file
     end;

     //return link to the created file
     Result := '<a href="' + GetFileName(nil, AFile, True) +
               '.recordlikes.html">' +
               Localize(dtDocumentationFilesLinkListsRecordLikes) + '</a>'
    end
   else
    Result := '';

 finally
  List.RemoveAll(False);               //free the list but not the identifiers
  List.Free;
 end;
end;








{Writes the documentation about the file.
~param AFile the file whose documentation should be written }
procedure THTMLHelpDoc.WriteFileDocumentation(AFile: TPascalFile);
var       F           :TextFile;     //the file to write the documentation in
          //counter through all kinds of identifier to generate documentation
          WType       :TWriteKind;   //about
          Dummy       :String;       //not used
begin
 StartContentList(AFile.InternalFileName);
 AddContentEntry(FileTypeNames[AFile.FileType] + ' ' + AFile.InternalFileName,
                 GetFileName(nil, AFile) + '.html');

 //create the file to write the documentation to
 CreateFile(F, GetFileName(nil, AFile),
               FileTypeNames[AFile.FileType] + ' ' + AFile.InternalFileName,
               AFile.InternalFileName);
 try
   //write type and name of the file
   WriteLn(F, '<h1 class=file>', FileTypeNames[AFile.FileType], ' ',
              AFile.InternalFileName, '</h1>');


   SetCommentIdent(nil, AFile);         //set file to get documentation

   //write lists of all identifiers in the file
   for WType := low(WType) to high(WType) do
    Write(F, WriteVarConstFuncs(AFile, WType), '   ');
   //write list of record-like types
   WriteLn(F, WriteRecordTypeList(AFile));


   WriteLn(F, '<hr>');                  //separate documentation of identifiers


   CurrentHelpContext := 0;             //no help context defined so far
   SetCommentIdent(nil, AFile);         //set file to get documentation
   Dummy := '';
   WriteLn(F, GetFileComment(Dummy));   //get and write the documentation
 finally
  EndFile(F);                           //close the file
 end;

 EndContentList;

 //check, if a help context was defined for this file
 CheckHelpContext(GetFileName(nil, AFile) + '.html');
end;






























{Write the links to the generated files by ~[link WriteClassesTreeFiles].
~param Kind the kind of the record-like types (record/class/interface/...)
~result a text including links to the generated files }
function THTMLHelpDoc.ClassListFileLinks(Kind: TRecordKind): String;
begin
 if GenerateXFigFiles then               //Xfig files have been generated?
  inc(FGeneratedFileCount);
 if GenerateWMFFiles then                //WMF files have been generated?
  inc(FGeneratedFileCount);

 Result := inherited ClassListFileLinks(Kind); //return links
end;

{Writes the hierarchy of the kind of the record-like types.
~param Kind the kind of the record-like types (record/class/interface/...)
~param Text the text (by ~[link GetClassListText]) of the tree of classes }
procedure THTMLHelpDoc.WriteClassList(Kind: TRecordKind; const Text: String);
begin
 AddContentEntry(Localize(Plurals[Kind]), DescFilePreFix[Kind] + 'List.html');

 inherited WriteClassList(Kind, Text);
end;








{Writes the documentation of all members of a certain kind of a record-like
 type.
~param Kind  the kind of members to write documentation about
~param Ident the record-like type containing the members
~result link to the list of members of that kind }
function THTMLHelpDoc.WriteMembers(Kind: TMemberKind;
                                   Ident: TRecordType): String;

          //names of the lists and legends
const     KindLegend: array[TMemberKind] of String =
                      ('Fields', 'Properties', 'Methods');
          //titles of the lists and legends
          KindTitles: array[TMemberKind] of TDocumentationTexts =
                      (dtDocumentationClassMembersFields,
                       dtDocumentationClassMembersProperties,
                       dtDocumentationClassMembersMethods);


 {Write the documentation of the members defined in this record-like type. }
 procedure WriteDocumentation;
 var       List    :TIdentifierList;     //list of identifiers in this class

  {Gets the list of members in the record-like type.
  ~param WhatClass the class the members have to be }
  procedure GetList(WhatClass: TIdentifierClass);
  var       i      :Integer;                  //counter through all members
            One    :TIdentifier;              //each member
  begin
   for i := 0 to Ident.IdentList.Count - 1 do //for each member
    begin
     One := Ident.IdentList[i];                 //get it
     //is of correct class and documented?
     if (One is WhatClass) and not DoNotDocumentIdentifier(One) then
      List.AddIdent(One);                         //add it
    end;
  end;

 var       i       :Integer;             //counter through the lists
           Member  :TIdentifier;         //each member
           F       :TextFile;            //file for documentation of member
           Dummy   :String;              //not used
 begin
  List := TIdentifierList.Create;        //create list for members
  try
    GetList(MemberKindClasses[Kind]);    //get the members in this class

    if not List.IsEmpty then             //if there are some members
     begin
      List.Sort;                           //sort them

      StartContentList(Localize(KindTitles[Kind]));

      for i := 0 to List.Count - 1 do      //for each member
       begin
        Member := List[i];                   //get it

        AddContentEntry(Member.Name, GetFileName(Member) + '.html');

        //create file for documentation of member
        CreateFile(F, GetFileName(Member), Ident.Name + '.' + Member.Name,
                   Ident.Name + ', ' + Member.Name + '; ' + Member.Name);
        try

          CurrentHelpContext := 0;           //no help context defined so far
          SetCommentIdent(Member, Member.InFile); //set member for comment

          //write links to the record-like type and the list of members of that
          //kind in the record-like type
          WriteLn(F, RecordKindNames[Ident.Kind], ' ',
                     GetIdentNameLink(Ident), '   ', Result);
          WriteLn(F, '<hr>');

          //write the declaration of the member
          WriteLn(F, Member.GetDescriptionString(Self, Ident),
                     '<br>');


          Dummy := '';
          //write documentation of member
          WriteLn(F, GetIdentComment(Dummy));

          //check, if a help context was defined for this member
          CheckHelpContext(GetFileName(Member) + '.html');
        finally
         EndFile(F);
        end;
       end; //for i := 0 to List.Count - 1

      EndContentList;
     end; //if not List.IsEmpty
  finally
   List.RemoveAll(False);                //free the list (without members)
   List.Free;
  end;
 end;



 {Write lists of all members of the kind.
 ~result if some members could be found }
 function WriteInheritedList: Boolean;
 var      F            :TextFile;            //file for the list of members

  {Writes the entry of an inherited member.
  ~param Member     the member (in TheRec and TheFile) to write
  ~param WriteClass if the class should also be written }
  procedure WriteInheritedMember(Member: TIdentifier; WriteClass: Boolean);
  var       Port         :TIdentPortabilities; //portability issues of member
  begin
   Write(F, '      <li>', GetScope(Member.Scope)); //write scope of the member

   Port := Member.Portability;
   if FDeprecatedList.IsIn(Member) then        //get its portability issues
    Include(Port, ipDeprecated);
   //write the portability issues
   Write(F, GetPortabilityIssues(Port));

   //if it is a read-only property, write an icon indicating that
   if (Kind = mkProperty) and TProperty(Member).IsReadOnly then
    Write(F, FCommentFormats.FReadOnlyIconText);

   if Kind = mkMethod then
    begin
     //if it is an abstract method, write an icon indicating that
     if faAbstract in TFunction(Member).Attributes then
      Write(F, FCommentFormats.FAbstractIconText);
     Write(F, '&nbsp;');
     //if it is a class method, write the indicating reserved word "class"
     if faClassMethod in TFunction(Member).Attributes then
      Write(F, ReservedWord('class'), ' ');
     //if it is a con-/destructor, indicate this by writting this
     if TFunction(Member).FuncKind in [fkConstructor, fkDestructor] then
      Write(F, ReservedWord(FuncNames[TFunction(Member).FuncKind]), ' ');
    end;

   //write link to the member
   Write(F, GetRecordFieldNameLink(Member,
                                   WriteClass and (Member.MemberOf <> Ident)),
            '</li>');
  end;

 var       AllList :TIdentifierList;       //list of all members
           i       :Integer;               //counter through the lists
           Member  :TIdentifier;           //each property
           LastRec :TRecordType;           //the type of the previous member
 begin
  AllList := TIdentifierList.Create;       //create list for all members
  try
    //get all members