uichtmlhelpdoc.pas

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

     if Ident is TRecordType then
      TheRecord := TRecordType(Ident)
     else
      TheRecord := Ident.MemberOf;
    end
   else
    TheRecord := nil;


   if Local then                         //should be local, without directory?
    Result := ''
   else
    begin
     //the name of the file (and its number) as the sub-directory
     Result := TheFile.InternalFileName;
     if TheFile.InternalNameIndex <> 0 then
      Result := Result + '.' + IntToStr(TheFile.InternalNameIndex);
     Result := Result + '/';
     if (FUseSubdirectories = sduFilesAndTypes) and Assigned(TheRecord) then
      Result := Result + TheRecord.Name + '/';
    end;

   //if in a record-like type
   if Assigned(TheRecord) and (FUseSubdirectories <> sduFilesAndTypes) then
    Result := Result + 'I_' + TheRecord.Name; //add prefix + record-like type

   //identifier in file/record-like type?
   if Assigned(Ident) and (Ident <> TheRecord) then
    begin
     //is inside a record-like type?
     if Assigned(TheRecord) and (FUseSubdirectories <> sduFilesAndTypes) then
      Result := Result + '.';                //add separating dot
     Result := Result + 'I_';              //add prefix and index and its name
     if Ident.InternalNameIndex <> 0 then
      Result := Result + IntToStr(Ident.InternalNameIndex);
     Result := Result + Ident.Name;
    end
   else
    if not Assigned(Ident) then          //just the file?
     Result := Result + 'File'             //use always this name for the file
    else
     if FUseSubdirectories = sduFilesAndTypes then //just the type?
      Result := Result + 'Type'              //this name for record-like types
  end
 else
  Result := inherited GetURIOf(Ident, TheFile); //use default URI
end;






{Returns a prefix for all links to images. Needed in order to use
 sub-directories.
~result a prefix for all links to images }
function TICHTMLHelpDoc.GetImagePrefix: String;
begin
 Result := '';
 //may be in a sub-directory?
 if (FUseSubdirectories <> sduNone) and assigned(CommentFile) then
  begin
   Result := '../';                          //have to go back one directory
   //currently in another sub-directory and need another one?
   if (FUseSubdirectories = sduFilesAndTypes) and //may be two levels deep?
      assigned(CommentIdent) and                 //and (in) a record-like type?
      (assigned(CommentIdent.MemberOf) or (CommentIdent is TRecordType)) then
    Result := '../' + Result;                      //go up another one level
  end;
end;




















{Writes the list of files, the DOM is generated by ~[link AddFileList].
~param Node the DOM of the list of files }
procedure TICHTMLHelpDoc.WriteFileList(Node: TICNode);
begin
 AddContentEntry(Localize(dtDocumentationLinkFiles), 'FileList');

 inherited WriteFileList(Node);          //write the list
end;




          //header titles of the lists of different kinds of identifiers in
          //files
const     DeclName: array[TWriteKind] of TDocumentationTexts =
                    (dtDocumentationFileDeclarationsHeaderVar,
                     dtDocumentationFileDeclarationsHeaderThreadVar,
                     dtDocumentationFileDeclarationsHeaderConst,
                     dtDocumentationFileDeclarationsHeaderResourceString,
                     dtDocumentationFileDeclarationsHeaderFunctions,
                     dtDocumentationFileDeclarationsHeaderSimpleTypes);
          //the classes of the lists of different kinds of identifiers in files
          DeclTypeClass: array[TWriteKind] of TIdentifierClass =
             (TVariable,       TVariable, TConstant,
              TResourceString, TFunction, TType);
          //the name of anchors to the beginning of the lists of different
          //kinds of identifiers in files
          ListName: array[TWriteKind] of String =
             ('Variables',       'ThreadVariables', 'Constants',
              'ResourceStrings', 'Functions',       'SimpleTypes');



{Writes the documentation about all identifiers of the given kind in the file
 and a list of them.
~param AFile     the file whose identifiers should be documented
~param WriteType the kind of identifiers to document
~result a link to the created list of all documented identifiers }
function TICHTMLHelpDoc.WriteVarConstFuncs(AFile: TPascalFile;
                                           WriteType: TWriteKind): String;
var      List          :TIdentifierList;  //list of the identifiers in the file

 {Gets the list of identifiers of the kind in the file. }
 procedure GetList;
 var       AClass :TIdentifierClass;      //class the identifiers have to be
           i      :Integer;               //counter through all identifiers
           Ident  :TIdentifier;           //each identifier
 begin
  AClass := DeclTypeClass[WriteType];     //get class of identifiers
  for i := 0 to AFile.Idents.Count - 1 do //for each identifier
   begin
    Ident := AFile.Idents[i];               //get it
    if (((Ident is AClass) and                //is of searched class and kind?
         (not (WriteType in [wkVar, wkThreadVar]) or
          (TVariable(Ident).IsThreadVar = (WriteType = wkThreadVar)))) or
        ((WriteType = wkConst) and (Ident is TEnumTypeItem))) and
       not DoNotDocumentIdentifier(Ident) then //and documented?
     List.AddIdent(Ident);                       //add it to the list
   end;
 end;

 {Creates the documentation of all identifiers in the list. }
 procedure CreateDocumentation;
 var       i           :Integer;       //counter through all identifiers
           Ident       :TIdentifier;   //each identifier
           F           :TBufferStream; //files for documentation of identifiers
           Comment     :TICSimpleComment; //the documentation of the identifier
 begin
  for i := 0 to List.Count - 1 do      //for each identifier
   begin
    Ident := List[i];                    //get it

    if not (Ident is TRecordType) then   //if not a record-like type
     begin
      SetCommentIdent(Ident, Ident.InFile); //set identifier for comment

      AddContentEntry(Ident.Name, GetFileName(Ident));

      F := CreateFile(GetFileName(Ident),
                      HandleRawText(AFile.InternalFileName + '.' + Ident.Name),
                      HandleRawText(AFile.InternalFileName + ', ' +
                                    Ident.Name + '; ' + Ident.Name));
      try
        //write link to the file and to the list of all identifiers of the kind
        F.WriteString(FileTypeNames[AFile.FileType]);
        F.WriteCharacter(' ');
        F.WriteString(GetFileNameLink(AFile));
        F.WriteString('   ');
        F.WriteString(Result);
        F.WriteString(NewLine);
        F.WriteString(TagConstants.hr);     //end the header

        //get and write the documentation of the identifier
        Comment := GetFinalIdentifierComment(Ident);
        try
          WriteNode(Comment.Content, F);

          //check, whether a help context was defined for this identifier
          CheckHelpContext(GetFileName(Ident) + FileExtension,
                           Comment.HelpContext);
        finally
         ReleaseFinalComment(Comment);       //release the documentation
        end;
      finally
       EndFile(F);
      end;
     end; //if not (Ident is TRecordType)
   end; //for i := 0 to List.Count - 1
 end;

 {Creates the linked list of identifiers in the file. }
 procedure CreateList;
 var       F         :TBufferStream;       //file for the list
           i         :Integer;             //counter through the list
           Ident     :TIdentifier;         //each identifier
           Port      :TIdentPortabilities; //its portability issues
 begin
  //create file for the list
  F := CreateFile(GetFileName(nil, AFile) + '.' + ListName[WriteType],
                  Localize(DeclName[WriteType]) +
                  Localize(dtDocumentationFileDeclarationsHeaderMiddle) +
                  HandleRawText(FileTypeNames[AFile.FileType] + ' ' +
                                AFile.InternalFileName),
                  HandleRawText(AFile.InternalFileName + ', ') +
                  Localize(DeclName[WriteType]));
  try
    F.WriteString(FileTypeNames[AFile.FileType]);
    F.WriteCharacter(' ');
    F.WriteString(GetFileNameLink(AFile));   //write link to the file
    F.WriteString(NewLine);
    F.WriteString(TagConstants.hr);          //end the header

    F.WriteString('<h3>');                   //write the title
    F.WriteString(Localize(DeclName[WriteType]));
    F.WriteString(Localize(dtDocumentationFileDeclarationsHeaderMiddle));
    F.WriteString(FileTypeNames[AFile.FileType]);
    F.WriteCharacter(' ');
    F.WriteString(AFile.InternalFileName);
    F.WriteString('</h3>');
    F.WriteString(NewLine);

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

      F.WriteString('<li>');
      F.WriteString(GetScope(Ident.Scope));    //write its scope

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

      if WriteType = wkFunc then               //for functions
       begin                                     //write their type
        F.WriteString(AsReservedWord(FuncNames[TFunction(Ident).FuncKind]));
        F.WriteCharacter(' ');
       end;

      F.WriteString(GetIdentNameLink(Ident));  //write its linked name
      F.WriteString('</li>');
      F.WriteString(NewLine);
     end;
    F.WriteString('</ul>');                  //end the list
    F.WriteString(NewLine);
  finally
   EndFile(F);                               //close the file
  end;
 end;


begin
 List := TIdentifierList.Create;           //create the list of the identifiers
 try
   GetList;                                //search identifiers of that kind

   if not List.IsEmpty then                //some identifiers found?
    begin
     List.Sort;                              //sort the list

     //include link to the list in the header of the file
     Result := '<a href="' + GetFileName(nil, AFile, True) + '.' +
               ListName[WriteType] + FileExtension + '">' +
               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 should be listed
~result a link to the generated list if it is not empty }
function TICHTMLHelpDoc.WriteRecordTypeList(AFile: TPascalFile): String;

 {Writes a linked list of record-like types.
 ~param F    the file to write the list to
 ~param List the list to be written
 ~param Kind the kind of the record-like types to be written }
 procedure WriteList(F: TBufferStream; 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
        F.WriteString('  <li><h4>');           //write header
        F.WriteString(Localize(Plurals[Kind]));
        F.WriteString('</h4>');
        F.WriteString(NewLine);
        F.WriteString('    <ul>');             //start new enumeration
        F.WriteString(NewLine);
        None := False;                         //some types of the kind found
       end;
      //write a link to the record-like type
      F.WriteString('      <li>');
      F.WriteString(GetIdentNameLink(Ident));
      F.WriteString('</li>');
      F.WriteString(NewLine);
     end;
   end;
  if not None then                      //record-like types of this kind found?
   begin
    F.WriteString('    </ul>');           //end the current enumeration
    F.WriteString(NewLine);
    F.WriteString('  </li>');
    F.WriteString(NewLine);
   end;
 end;


var      List        :TIdentifierList;    //the record like types in the file
         i           :Integer;            //counter through all identifiers
         Ident       :TIdentifier;        //each identifier
         F           :TBufferStream;      //the file of the list
         Kind        :TRecordKind;        //each kind of record-like types
begin
 List := TIdentifierList.Create;          //create list of record-like types
 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