udocumentdoc.pas

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

{Returns the parameters of the program.
~param ProgramFile the program whose parameters should be returned
~result the parameters of the program }
function TDocumentDoc.GetProgramParameters(ProgramFile: TPascalFile): String;
var      i           :Integer;        //position of a space separated comma
begin
 Result := ProgramFile.ProgramParameters;         //return the parameters

 assert(Result <> '');
 assert(copy(Result, 1, 2) = '( ');
 assert(copy(Result, length(Result) - 1, 2) = ' )');

 Result := copy(Result, 3, length(Result) - 4);   //remove the braces

 i := pos(' ,', Result);
 while i <> 0 do                                  //remove spaces before commas
  begin
   Delete(Result, i, 1);
   i := pos(' ,', Result);
  end;

 Result := HandleRawText(Result);                 //return in the format
end;


{Returns the list of all required packages of a package.
~param PackageFile the package file whose required packages should be returned
~result the required packages of the package }
function TDocumentDoc.GetRequiredPackages(PackageFile: TPascalFile): String;
var      i           :Integer;        //runner through the packages
         PackageName :String;         //name of each package
         FoundFile   :TPascalFile;    //the file of each package
begin
 Result := '';
 for i := 0 to PackageFile.RequiredPackages.Count - 1 do //for each package
  begin
   if i <> 0 then                                    //not first package?
    Result := Result + HandleRawText(', ');            //insert separating ", "

   PackageName := PackageFile.RequiredPackages[i];   //get name of the package
   FoundFile := FFiles.GetFileByName(PackageName);   //search package
   if assigned(FoundFile) and                        //if known/parsed and
      not DoNotDocumentIdentifier(nil, FoundFile) then //documented
    Result := Result + GetFileNameLink(FoundFile)        //add link
   else
    Result := Result + IdentifierText(PackageName);      //add name
  end;
end;


{Returns the text of an exported function/identifier.
~param Ident the exported function/identifier that should be returned
~result the exported function/identifier as a text }
function TDocumentDoc.GetExportsDeclaration(Ident: TExportIdentifier): String;
var      TheIdent    :TIdentifier;       //the exported identifier
begin
 TheIdent := FindIdentifier(Ident.Name, Ident.InFile, Ident.Position);
 //if found, add link to it documented
 if assigned(TheIdent) and not DoNotDocumentIdentifier(TheIdent) then
  Result := GetIdentNameLink(TheIdent, pos('.', Ident.Name) <> 0)
 else
  Result := IdentifierText(Ident.Name);            //or just the text

 if Ident.ExportIndex <> '' then      //if index for export specified, add it
  Result := Result + ' ' + ReservedWord('index') + ' ' +
            ExprText(Ident.ExportIndex, Ident);
 if Ident.ExportName <> '' then       //if name for export specified, add it
  Result := Result + ' ' + ReservedWord('name') + ' ' +
            ExprText(Ident.ExportName, Ident);
 if Ident.Resident then               //if directive "resident" specified
  Result := Result + ' ' + ReservedWord('resident');       //add it
end;

{Returns the list of all exported functions/identifiers.
~param AFile the file whose exported functions should be returned
~result the exported identifiers of the file }
function TDocumentDoc.GetExports(AFile: TPascalFile): String;
var      i           :Integer;       //counter through all exported identifiers
         Ident       :TIdentifier;   //each identifier
         First       :Boolean;       //if it is the first added identifier
begin
 Result := '';                              //no exported identifiers so far
 First := True;                             //next identifier is the first
 for i := 0 to AFile.Exporteds.Count - 1 do //for each
  begin
   Ident := AFile.Exporteds[i];               //get it
   if not DoNotDocumentIdentifier(Ident) then   //documented?
    begin
     if First then                                //the first one?
      First := False                                //next is not the first
     else
      Result := Result + HandleRawText(', ');       //add a separator

     //add the documentation of the identifier
     Result := Result + GetExportsDeclaration(TExportIdentifier(Ident));
    end;
  end;
end;

{Returns the list of all used/contained units in a part.
~param ForFile  the file using the files and the list is created for
~param FilePart the part of the file for which the list should be created
~result all used/contained units in the part }
function TDocumentDoc.GetUnitList(ForFile: TPascalFile;
                                  FilePart: TFilePart): String;
var      Parser      :TTokenParser;  //tokenizer of the exported functions
         UnitName    :String;        //the names of the used/contained units
         Token       :String;        //a token "," separating the functions
         TheUnit     :TPascalFile;   //the used/contained file
         Index       :Integer;       //index of file in FirstUnitSearch
begin
 Parser := TTokenParser.Create;      //create the tokenizer
 try
   Parser.ParseString(ForFile.UsesClauses[FilePart]); //parse list of units

   Result := '';
   while Parser.GetToken(UnitName) do              //while units left
    begin
     while Parser.GetToken(Token) and (Token <> ',') do //skip all separators
      ;

     if Result <> '' then                            //not first unit
      Result := Result + HandleRawText(', ');          //add separator

     Token := UnitName;                              //save used name
     UnitName := ForFile.GetUnitAlias(UnitName);     //if aliased get real unit

     //search unit in list
     Index := ForFile.UsedUnitList[FilePart].IndexOf(UnitName);
     if Index <> -1 then                             //found in list?
      //use the file in the list
      TheUnit := TPascalFile(ForFile.UsedUnitList[FilePart].Objects[Index])
     else
      TheUnit := FFiles.GetFileByName(UnitName);       //search in all files

     //unit is known and documented?
     if assigned(TheUnit) and not DoNotDocumentIdentifier(nil, TheUnit) then
      begin
       Result := Result + GetFileNameLink(TheUnit);    //add link
       if UnitName <> Token then                       //was an alias?
        Result := Result + Localize(dtUnitUsedByAliasPre) +  //add information
                  IdentifierText(Token) + Localize(dtUnitUsedByAliasPost);
      end
     else
      Result := Result + IdentifierText(Token);        //add (original) name
    end;
 finally
  Parser.Free;                                     //free tokenizer
 end;
end;
















{Returns the inheritance list of this record-like type.
~param Ident the identifier whose inheritance list should be returned
~result the inheritance list of this identifier
~todo change direction => prepend to string (not urgent) }
function TDocumentDoc.GetAncestorList(Ident: TRecordType): String;

 {Adds the class to the resulting list.
 ~param Ident the identifier to add to the list }
 procedure GetClass(AClass: TRecordType);
 var       IsAbstract     :Boolean;      //if the identifier is abstract
 begin
  IsAbstract := AClass.IsAbstract;         //check, if it is astract
  if IsAbstract then                       //in that case format it like that
   Result := Result + FDocumentFormats.FAncestorListAbstractPre;
  Result := Result + GetIdentNameLink(AClass);   //add the identifier
  if IsAbstract then
   Result := Result + FDocumentFormats.FAncestorListAbstractPost;
  //add an arrow to the next class in the inheritance list
  Result := Result + FDocumentFormats.FAncestorListArrow;
 end;

 {Adds the class and all parent classes (ancestors) to the list.
 ~param Ident the identifier to add to the list
 ~param AFile the file the identifier is declared in }
 procedure GetParent(Parent: TRecordType);
 var       ItsParent       :TRecordType;   //the parent of this identifier
           NotDocumented   :Boolean;       //whether parent is not documented
           IsAbstract      :Boolean;       //if the identifier is abstract
 begin
  if assigned(Parent) then                 //identifier known?
   begin
    assert(not DoNotDocumentIdentifier(Parent));

    if assigned(Parent.IdentParent) then     //has a parent class?
     begin
      ItsParent := Parent.GetParent;           //get it

      NotDocumented := assigned(ItsParent) and //should not be documented?
                       DoNotDocumentIdentifier(ItsParent);
      if NotDocumented then
       ItsParent := nil;                         //end ancestor list here

      GetParent(ItsParent);                    //and add it to list
      if not assigned(ItsParent) then          //parent not known?
       begin
        if NotDocumented then                    //because it isn't documented?
         //indicate that some entries are missing
         Result := Result + FDocumentFormats.FAncestorListMissing
        else
         if Parent.Kind in [rkClass, rkInterface] then  //has a default parent?
          begin
           //not default parent defined?
           if ((LowerCase(Parent.IdentParent.DefIdent) <>
                LowerCase(DocumentationTexts[DefParentClassNameHeader[
                                                        Parent.Kind]].T)) and
               (LowerCase(Parent.IdentParent.DefIdent) <>
                'system.' +
                LowerCase(DocumentationTexts[DefParentClassNameHeader[
                                                        Parent.Kind]].T))) then
            //add an entry for it and indicate that some entries may be missing
            Result := Result + FDocumentFormats.FAncestorListMissing +
                               IdentifierText(Parent.IdentParent.DefIdent) +
                               FDocumentFormats.FAncestorListArrow;
          end
         else
          //just add the name of the parent class
          Result := Result + IdentifierText(Parent.IdentParent.DefIdent) +
                             FDocumentFormats.FAncestorListArrow;
       end; //if not assigned(ItsParent)
     end; //if assigned(Parent.IdentParent)

    if Parent = Ident then                          //is the final identifier?
     begin
      Result := Result + FDocumentFormats.FAncestorListFinalPre;
      IsAbstract := Parent.IsAbstract;                //check if it is abstract
      if IsAbstract then                              //if it is format it so
       Result := Result + FDocumentFormats.FAncestorListAbstractPre;
      Result := Result + IdentifierText(Parent.Name); //add final entry
      if IsAbstract then
       Result := Result + FDocumentFormats.FAncestorListAbstractPost;
      Result := Result + FDocumentFormats.FAncestorListFinalPost;
     end
    else
     GetClass(Parent);                                //add the entry
   end //if assigned(Parent)
  else
   if Ident.Kind in [rkClass, rkInterface] then     //has default parent?
    //add entry for the default parent class
    Result := Result + Localize(DefParentClassNameHeader[Ident.Kind]) +
                       FDocumentFormats.FAncestorListArrow;
 end;

begin
 Result := '';                       //list is empty so far
 GetParent(Ident);                   //fill it with the inheritance list
end;



{Returns a list of all implemented interfaces correctly formatted and linked.
~param Ident the identifier (of a class) whose list of all implemented
             interfaces should be returned
~result a list of all implemented interfaces }
function TDocumentDoc.GetInterfaceLinks(Ident: TRecordType): String;
var      i           :Integer;     //counter through all implemented interfaces
         Interf      :TIdentifier; //an implemented interface
         First       :Boolean;     //if it is the first added identifier
begin
 Result := '';                     //none implemented so far
 First := True;                    //next identifier is the first
 for i := 0 to Ident.Implementing.Count - 1 do //for each implemented interface
  begin
   Interf := Ident.Implementing[i];              //get implemented interface
   assert(Interf is TIdentType);
   if assigned(TIdentType(Interf).TheType) and   //if interface known and
      not DoNotDocumentIdentifier(TIdentType(Interf).TheType) then //documented
    begin
     if First then                                 //the first one?
      First := False                                 //next is not the first
     else
      Result := Result + HandleRawText(', ');        //add a separating comma
     Result := Result + GetIdentNameLink(TIdentType(Interf).TheType); //& link
    end;
// else
//  Result := Result + IdentifierText(TIdentType(Interf).DefIdent);  //add name
  end;
end;

{Returns a list of all in parent-classes implemented interfaces correctly
 formatted and linked.
~param Ident the identifier (of a class) whose list of all interfaces
             implemented by its ancestors should be returned
~result a list of all implemented interfaces }
function TDocumentDoc.GetParentInterfaceLinks(Ident: TRecordType): String;
var      S           :String;   //the list of implemented interfaces in a class
begin
 Ident := Ident.GetParent;      //start with its parent

 Result := '';                  //none found so far
 while assigned(Ident) do