uichtmlhelpdoc.pas

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

    end;

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

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

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

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



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

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


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

   //write lists (and documentation) of all identifiers in the file
   for WType := Low(WType) to High(WType) do
    begin
     F.WriteString(WriteVarConstFuncs(AFile, WType));
     F.WriteString(' &nbsp; ');
     F.WriteString(NewLine);
    end;
   //write list of record-like types
   F.WriteString(WriteRecordTypeList(AFile));
   F.WriteString(NewLine);

   F.WriteString(TagConstants.hr);      //separate documentation of identifiers


   SetCommentIdent(nil, AFile);         //set file to get documentation
   Comment := GetFinalFileComment(AFile); //and get it
   try
     //write the documentation of the file
     WriteNode(Comment.Content, F);

     //check, whether a help context was defined for this file
     CheckHelpContext(GetFileName(nil, AFile) + FileExtension,
                      Comment.HelpContext);
   finally
    ReleaseFinalComment(Comment);       //release the documentation
   end;
 finally
  EndFile(F);                           //close the file
 end;

 EndContentList;
end;



























{Writes the hierarchy of the record-like types of the specified kind.
~param Kind the kind of the record-like types (record/class/interface/...)
~param Node the DOM (by ~[link AddClassList]) of the tree of classes }
procedure TICHTMLHelpDoc.WriteClassTree(Kind: TRecordKind; Node: TICNode);
begin
 AddContentEntry(Localize(Plurals[Kind]), DescFilePreFix[Kind] + 'List');

 inherited WriteClassTree(Kind, Node);    //write the hierarchy
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 a link to the list of members of that kind }
function TICHTMLHelpDoc.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);


 {Writes the documentation of the members defined in this record-like type. }
 procedure WriteDocumentation;
 var       List    :TIdentifierList;     //the list of members in the 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 list
           Member  :TIdentifier;         //each member
           F       :TBufferStream;       //file to write the documentation to
           Comment :TICSimpleComment;    //the documentation of the member
 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));

        //create file for documentation of member
        F := CreateFile(GetFileName(Member),
                        HandleRawText(Ident.Name + '.' + Member.Name),
                        HandleRawText(Ident.Name + ', ' + Member.Name + '; ' +
                                      Member.Name));
        try
          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
          F.WriteString(RecordKindNames[Ident.Kind]);
          F.WriteCharacter(' ');
          F.WriteString(GetIdentNameLink(Ident));
          F.WriteString('   ');
          F.WriteString(Result);
          F.WriteString(NewLine);
          F.WriteString(TagConstants.hr);

          Comment := GetFinalIdentifierComment(Member); //get its documentation
          try
            WriteNode(Comment.Content, F);              //and write it

            //check, whether a help context was defined for this member
            CheckHelpContext(GetFileName(Member) + FileExtension,
                             Comment.HelpContext);
          finally
           ReleaseFinalComment(Comment);          //release the documentation
          end;
        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            :TBufferStream;      //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
   F.WriteString('      <li>');
   F.WriteString(GetScope(Member.Scope)); //write scope of the member

   Port := Member.Portability;            //get its portability issues
   if Comments.Comment[Member].Deprecateds.HasChildren then
    Include(Port, ipDeprecated);
   //write the portability issues
   F.WriteString(GetPortabilityIssues(Port));

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

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

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

 var       AllList :TIdentifierList;       //list of all members of the kind
           i       :Integer;               //counter through the lists
           Member  :TIdentifier;           //each member
           LastRec :TRecordType;           //type containing previous member
 begin
  AllList := TIdentifierList.Create;       //create list for all members
  try
    //get all members
    GetInheritedList(Ident, AllList, MemberKindClasses[Kind]);

    Result := not AllList.IsEmpty;
    if Result then                         //some members?
     begin

      //create file for the list of members
      F := CreateFile(GetFileName(Ident) + '.' + KindLegend[Kind],
                      Localize(KindTitles[Kind]) +
                      Localize(dtDocumentationClassInheritedInMiddle2) +
                      HandleRawText(RecordKindNames[Ident.Kind] + ' ' +
                                    Ident.Name),
                      HandleRawText(Ident.Name + ', ') +
                      Localize(KindTitles[Kind]));
      try
        F.WriteString('<h1 class="member">');  //write header of the members
        F.WriteString(Localize(KindTitles[Kind]));
        F.WriteString(Localize(dtDocumentationClassInheritedInMiddle2));
        F.WriteString(RecordKindNames[Ident.Kind]);
        F.WriteCharacter(' ');
        F.WriteString(Ident.Name);
        F.WriteString(':</h1>');
        F.WriteString(NewLine);

        F.WriteString(GetIdentNameLink(Ident));
        F.WriteString(' <a href="');
        F.WriteString(GetFileName(Ident, nil, True));
        F.WriteCharacter('.');
        F.WriteString(KindLegend[Kind]);
        F.WriteStrings(['.Alpha', FileExtension, '">']);
        F.WriteString(Localize(dtDocumentationClassesLinkMemberListAlphabetically));
        F.WriteString('</a>');
        F.WriteString(NewLine);

        F.WriteString(TagConstants.hr);        //end the header

        F.WriteString('<ul>');                 //start list
        F.WriteString(NewLine);

        AllList.SortTo(Ident);                 //sort the list
        LastRec := nil;
        for i := 0 to AllList.Count - 1 do     //for each inherited member
         begin
          Member := AllList[i];                  //get it

          if LastRec <> Member.MemberOf then     //in a new class?
           begin
            if Assigned(LastRec) then              //not the first one?
             begin
              F.WriteString('    </ul>');            //end last list
              F.WriteString(NewLine);
              F.WriteString