uhtmldoc.pas

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

 var       i      :Integer;               //counter through all identifiers
           Ident  :TIdentifier;           //each identifier
 begin
  if not List.IsEmpty then                //if the list os 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
       Write(F, ', ');                         //write a separator
      //write a link to the record-like type
      Write(F, GetIdentNameLink(Ident));
     end;
    WriteLn(F, '<br>');                    //end the current line
   end
  else
   //write the empty list
   WriteLn(F, '<i>', Localize(dtDocumentationEmptyList), '</i><br>');
 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
   GetList(sInterface, List);            //get the list of the identifiers
   ImplList := TIdentifierList.Create;   //create implementation list
   try
     if not NoPrivateOnlyInterface then  //implementation should be documented?
      GetList(sImplementation, ImplList);  //get the identifier
     if not List.IsEmpty or not ImplList.IsEmpty then //identifiers found?
      begin
       //write the header of the kind of record-like types
       WriteLn(F, '<h2 class=identslist>',
                  Localize(dtDocumentationFileDeclarationsHeaderPrefix),
                  Localize(Plurals[Kind]), ':</h2>');

       //write header for record-like types in the interface part
       Write(F, '  <b class=identsscope>',
                Localize(dtDocumentationFileDeclarationsHeaderGlobalPrefix),
                Localize(Plurals[Kind]), ':</b> ');
       WriteList(List);                      //write the list

       //identifiers in the implementation part should be documented?
       if not NoPrivateOnlyInterface then
        begin
         //write header for record-like types in the implementation part
         Write(F, '  <b class=identsscope>',
                  Localize(dtDocumentationFileDeclarationsHeaderLocalPrefix),
                  Localize(Plurals[Kind]), ':</b> ');
         WriteList(ImplList);                  //and write the list
        end;
       WriteLn(F, '<hr>');  //end the section of this kind of record-like types
      end;
   finally
    ImplList.RemoveAll(False);   //free the lists (without identifiers)
    ImplList.Free;
   end;
 finally
  List.RemoveAll(False);
  List.Free;
 end;
end;




{Writes the documentation about all identifiers of the given kind in the file.
~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 THTMLDoc.WriteVarConstFuncs(var F: TextFile; List: TIdentifierList;
                                      WriteType: TWriteKind);
var       i       :Integer;       //counter through all identifiers
          Ident   :TIdentifier;   //each identifier
          Dummy   :String;        //not used
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
   WriteLn(F, '<h2 class=idents><a name="', AnchorDeclName[WriteType], '">',
              Localize(DeclName[WriteType]), ':</a></h2>');

   WriteLn(F, '<dl class=idents>'); //start list of identifiers
   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);


     //start definition of the identifier with an anchor
     Write(F, '  <dt class=ident><a name="I_');
     if Ident.InternalNameIndex <> 0 then
       Write(F, Ident.InternalNameIndex);
     Write(F, Ident.Name, '">');
     Write(F, GetScope(Ident.Scope)); //write its scope
     Write(F, '</a> ');               //for the anchor

     if WriteType = wkSimpleType then //if it is a simple type
      Write(F, Ident.Name, ' = ');      //write the name of the identifier

     //write the definition of the identifier
     Write(F, Ident.GetDescriptionString(Self, Ident));

     WriteLn(F, '</dt>');             //end the definition
     Write(F, '  <dd class=ident>');  //and start the documentation

     Dummy := '';
     //write the documentation of the identifier
     Write(F, GetIdentComment(Dummy));
     if WriteType = wkFunc then       //if it is a function
      Write(F, '<br>');                 //insert some space to next one
     WriteLn(F, '</dd>');             //end entry of the identifier

    end; //for i := 0 to List.Count - 1

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


{Writes the documentation about the file.
~param AFile the file whose documentation should be written }
procedure THTMLDoc.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);                  //clear the list
  AClass := DeclTypeClass[WriteType];     //get class of identifiers to get
  for i := 0 to AFile.Idents.Count - 1 do //for each identifier
   begin
    Ident := AFile.Idents[i];               //get it
    //is of the searched class?
    if (((Ident is AClass) and
        //and even if types are searched, is not a record-like type?
        ((WriteType <> wkSimpleType) or not (Ident is TRecordType)) and
        //and is the correct variable or thread-variable?
        (not (WriteType in [wkVar, wkThreadVar]) or
         (TVariable(Ident).IsThreadVar = (WriteType = wkThreadVar)))) or
        //handle items of enumerations as constants 
        ((WriteType = wkConst) and (Ident is TEnumTypeItem))) and
       not DoNotDocumentIdentifier(Ident) then //and documented?
     List.AddIdent(Ident);                     //add the identifier to the list
   end;
 end;

var       F       :TextFile;        //the file to write the documentation in
          S       :String;          //general string
          //counter through all kinds of record-like types to genrate links to
          rk      :TRecordKind;
          //list of identifiers to generate documentation about
          List    :TIdentifierList;
          //counter through all kinds of identifier to generate documentation
          WType   :TWriteKind;      //about
          Dummy   :String;          //not used
begin
 if AFile.InternalNameIndex <> 0 then    //get index of the file as a prefix
  S := IntToStr(AFile.InternalNameIndex)
 else
  S := '';
 //create the file to write the documentation to
 CreateFile(F, 'File_' + S + AFile.InternalFileName,
               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
   Dummy := '';
   WriteLn(F, GetFileComment(Dummy));   //get and write the documentation

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

   //write lists of all identifiers in the file
   for WType := low(WType) to pred(high(WType)) do
    WriteVarConstFuncsList(F, AFile, WType);
   for rk := low(rk) to high(rk) do     //for record-like types write
    WriteRecordTypeList(F, AFile, rk);    //only links to their documentation
   assert(high(WType) = wkFunc);
   WriteVarConstFuncsList(F, AFile, wkFunc); //functions at the end

   List := TIdentifierList.Create;      //create list for all identifiers
   try
     for WType := low(WType) to high(WType) do  //for each kind of identifiers
      begin
       GetList(List, WType);                      //get list of the identifiers
       WriteVarConstFuncs(F, List, WType);        //and write it
      end;
   finally
    List.RemoveAll(False);              //free the list of the identifiers
    List.Free;
   end;

 finally
  EndFile(F);                           //close the file
 end;
end;





























{Writes the documentation of all members of a certain kind of a record-like
 type.
~param F        the file to write the documentation to
~param Heading  the heading for the lists of members, plural form
~param Kind     the kind of members to write documentation about
~param FuncKind the kind of methods if Kind is ~[link mkMethod]
~param Ident    the record-like type containing the members }
procedure THTMLDoc.WriteMembers(var F: TextFile; const Heading: String;
                                Kind: TMemberKind; FuncKind: TFunctionKind;
                                Ident: TRecordType);


 {Write the list of members direct in the record-like type.
 ~result if some members are direct in the record-like type }
 function WriteThisList: Boolean;
 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;

  {Gets the list of methods in the record-like type.
  ~param Kinds the inds of the methods to get }
  procedure GetMethods(Kinds: TFunctionKinds);
  var       i         :Integer;               //counter through all members
            Func      :TIdentifier;           //each member
  begin
   for i := 0 to Ident.IdentList.Count - 1 do //for each member
    begin
     Func := Ident.IdentList[i];                //get it
     if (Func is TFunction) and
        (TFunction(Func).FuncKind in Kinds) and //is correct kind of method?
        not DoNotDocumentIdentifier(Func) then  //and documented?
      List.AddIdent(Func);                        //add it
    end;
  end;

 var       Kinds   :TFunctionKinds;      //kinds of methods to get
           i       :Integer;             //counter through the lists
           Member  :TIdentifier;         //each member
           Dummy   :String;              //not used
 begin
  List := TIdentifierList.Create;        //create list for members
  try                                    //get all members in this class
    if Kind = mkMethod then              //methods should be documented?
     begin                                 //get kinds of methods
      if FuncKind = fkFunction then
       Kinds := [fkFunction, fkProcedure]
      else
       Kinds := [FuncKind];
      GetMethods(Kinds);                   //get the methods
     end
    else
     GetList(MemberKindClasses[Kind]);     //get the fields/properties

    Result := not List.IsEmpty;
    if Result then                       //if there are some members
     begin
      List.Sort;                           //sort them
      //start documentation of members
      WriteLn(F, '<h2 class=member>', Heading, ':</h2>');
      WriteLn(F, '<dl class=member>');     //start list

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

        //set identifier for getting its documentation
        SetCommentIdent(Member, Member.InFile);



        Write(F, '<dt class=member><a name="I_'); //start entry of the member
        if Member.InternalNameIndex <> 0 then  //with an anchor
          Write(F, Member.InternalNameIndex);
        //write its scope
        Write(F, Member.Name, '">', GetScope(Member.Scope), '</a>');

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

        //write its portability issues
        Write(F, GetPortabilityIssues(Member.Portability));

        //if it is an abstract method, write an indicating icon
        if (Kind = mkMethod) and
           (faAbstract in TFunction(Member).Attributes) then
         Write(F, FCommentFormats.FAbstractIconText);

        //and write its declaration and end its definition
        Write(F, ' ', Member.GetDescriptionString(Self, Ident), '</dt>');

        Dummy := '';                         //get and write it
        WriteLn(F, '<dd class=member>', GetIdentComment(Dummy), '<br></dd>');
       end; //for i := 0 to List.Count - 1

      WriteLn(F, '</dl>');                 //end list of members
     end; //if Result

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