udocumentdoc.pas

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

   assert(pos('.', Name) = 0);

   //search the identifier in the class and its ancestors
   Ident := MethodOf.FindMember(Name, MethodOf.InFile, True);
   //check if the identifier is documented
   if assigned(Ident) and not DoNotDocumentIdentifier(Ident) then
    Ident := nil;

   if assigned(Ident) then            //identifier found?
    //generate a link to it
    Result := GetRecordFieldNameLink(Ident)
   else
    Result := IdentifierText(Name);     //just return the text
  end;
end;

























{Returns the number of available options in generators of this class.
~result the number of available "expert"-options
~see GetOptionDescription
~see GetOption
~see SetOption }
class function TDocumentDoc.GetOptionCount: Cardinal;
begin
 Result := inherited GetOptionCount + 4;
end;

{Gets a description of an "expert"-option.
~param Index index of the option to get data of
~param Desc  out: the description of the option (name, type, default value,
                  etc.)
~see GetOptionCount }
class procedure TDocumentDoc.GetOptionDescription(Index: Cardinal;
                                                 var Desc: TOptionDescription);
var             PreOptionCount :Cardinal;  //number of options in parent class
begin
 PreOptionCount := inherited GetOptionCount; //get number of options in parent
 if Index < PreOptionCount then              //an option in the parent class?
  inherited GetOptionDescription(Index, Desc)  //forward to parent's method
 else
  begin
   ClearDescription(Desc);               //clear structure
   case Index - PreOptionCount of        //depending on index of option
     0: begin                            //set the values describing the option
         Desc.Name := 'GenerateFileTreeFiles';
         Desc.Category := 'Generation.Files';
         Desc.Description := 'If the files showing the inter-dependence between the files should be generated.';
         Desc.DataType := otBoolean;
         Desc.DefaultValue.BoolData := False;
        end;
     1: begin
         Desc.Name := 'GenerateClassesTreeFiles';
         Desc.Category := 'Generation.Files';
         Desc.Description := 'If the files showing the inheritance tree of classes should be generated.';
         Desc.DataType := otBoolean;
         Desc.DefaultValue.BoolData := False;
        end;
     2: begin
         Desc.Name := 'GenerateXFigFiles';
         Desc.Category := 'Generation.Files';
         Desc.Description := 'If X-fig files should be generated.';
         Desc.DataType := otBoolean;
         Desc.DefaultValue.BoolData := False;
        end;
     3: begin
         Desc.Name := 'GenerateWMFFiles';
         Desc.Category := 'Generation.Files';
         Desc.Description := 'If WMF files should be generated.';
         Desc.DataType := otBoolean;
         Desc.DefaultValue.BoolData := False;
        end;
   else
    assert(Index >= GetOptionCount);       //invalid index!
    raise EInvalidOption.Create('Invalid index for option supplied!');
   end;
  end;
end;

{Gets the value of an option. Call ~[link GetOptionDescription] to get the type
 and the meaning of the option.
~param Index index of the option to get the value of
~result the value of the option
~see GetOptionCount
~see GetOptionDescription
~see SetOption }
function TDocumentDoc.GetOption(Index: Cardinal): TOptionValue;
var      PreOptionCount :Cardinal;     //number of options in parent class
begin
 PreOptionCount := inherited GetOptionCount; //get number of options in parent
 if Index < PreOptionCount then              //an option in the parent class?
  Result := inherited GetOption(Index)         //forward to parent's method
 else
  begin
   case Index - PreOptionCount of             //depending on index of option
     0: Result.BoolData := FGenerateFileTreeFiles;        //get the value
     1: Result.BoolData := FGenerateClassesTreeFiles;
     2: Result.BoolData := FGenerateXFigFiles;
     3: Result.BoolData := FGenerateWMFFiles;
   else
    assert(Index >= GetOptionCount);          //invalid index!
    raise EInvalidOption.Create('Invalid index for option supplied!');
   end;
  end;
end;

{Sets the value of an option. Call ~[link GetOptionDescription] to get the type
 and the meaning of the option.
~param Index index of the option to set the value
~param Value the new value of the option
~see GetOptionCount
~see GetOptionDescription
~see GetOption }
procedure TDocumentDoc.SetOption(Index: Cardinal; const Value: TOptionValue);
var       PreOptionCount :Cardinal;   //number of options in parent class
begin
 PreOptionCount := inherited GetOptionCount; //get number of options in parent
 if Index < PreOptionCount then              //an option in the parent class?
  inherited SetOption(Index, Value)            //forward to parent's method
 else
  case Index - PreOptionCount of               //depending on index of option
    0: FGenerateFileTreeFiles := Value.BoolData;    //set the value
    1: FGenerateClassesTreeFiles := Value.BoolData;
    2: FGenerateXFigFiles := Value.BoolData;
    3:
{$IFNDEF LINUX}
       FGenerateWMFFiles := Value.BoolData
{$ENDIF}
       ;
  else
   assert(Index >= GetOptionCount);     //invalid index!
   raise EInvalidOption.Create('Invalid index for option supplied!');
  end;
end;








{Returns the text (formatted) in the format of the documentation. Any special
 characters are encoded so the text will appear as is.
~param Text the text to "quote", to return as is
~result the quoted text }
function TDocumentDoc.HandleRawText(const Text: String): String;
begin
 Result := Text;                        //by default nothing to quote
end;




{Returns the current and for the current format escaped text.
~param Text the identifier of the text to localize and return in the current
            format
~result the requested text localized in the current format }
function TDocumentDoc.Localize(Text: TDocumentationTexts): String;
begin
 Result := HandleRawText(DocumentationTexts[Text].T);
end;

{Returns the current and for the current format escaped text with the
~param Text the identifier of the text containing the format to localize and
            return in the current format
~param Args additional arguments for the text
~result the requested text localized in the current format }
function TDocumentDoc.LocalizeFmt(Text: TDocumentationTexts;
                                  const Args: array of const): String;
begin
 Result := HandleRawText(Format(DocumentationTexts[Text].T, Args));
end;






{Returns the unique ID of an identifier to be used in the documentation, for
 instance to create a link to it.
~param Ident   the identifier to return a link to (may be nil, to return a link
               to the file)
~param TheFile the file, if it is not an identifier
~result the unique ID of the identifier }
function TDocumentDoc.GetURIOf(Ident: TIdentifier;
                               TheFile: TPascalFile = nil): String;
begin
 assert(assigned(Ident) <> assigned(TheFile));
 assert(not DoNotDocumentIdentifier(Ident, TheFile));

 if assigned(Ident) then      //identifier in file/record-like type ?
  TheFile := Ident.InFile;      //use its file
 assert(assigned(TheFile));

 //add the file with a prefix and it's number
 Result := 'File_';
 if TheFile.InternalNameIndex <> 0 then
  Result := Result + IntToStr(TheFile.InternalNameIndex);
 Result := Result + TheFile.InternalFileName;

 if assigned(Ident) then      //identifier in file/record-like type ?
  begin
   if assigned(Ident.MemberOf) then   //if in record-like type
    //add record-like type with prefix
    Result := Result + '.I_' + Ident.MemberOf.Name;

   Result := Result + '.I_';       //add prefix and index and its name
   if (Ident.InternalNameIndex <> 0) and not (Ident is TRecordType) then
    Result := Result + IntToStr(Ident.InternalNameIndex);
   Result := Result + Ident.Name;
  end;
end;






















{Returns the token of a string (formatted) in the format of the documentation.
 Here is the place to apply some special formats for string conmstants.
~param StringToken the string token
~result the quotet string token in a special format (or not) }
function TDocumentDoc.FormatStringToken(const StringToken: String): String;
begin
 Result := HandleRawText(StringToken);  //here no special formatting by default
end;








{Returns a string containing a link to the given file.
~param TheFile the file to link to
~result a string containing a link to the file }
function TDocumentDoc.GetFileNameLink(TheFile: TPascalFile): String;
begin
 assert(assigned(TheFile));
 assert(not DoNotDocumentIdentifier(nil, TheFile));

 //return link to the file
 Result := FDocumentFormats.FPreLinkText + GetURIOf(nil, TheFile) +
           FDocumentFormats.FMiddleLinkText +
           IdentifierText(TheFile.InternalFileName) +
           FDocumentFormats.FPostLinkText;
end;

{Returns a string containing a link to the given identifier. The identifier
 can't be declared inside a record-like type (use ~[link
 .GetRecordFieldNameLink] for that) but must be top-level declared inside the
 file.
~param Ident     the identifier to link to
~param WriteFile if the file (also as a link) should be written
~result a string containing a link to the identifier (and the file) }
function TDocumentDoc.GetIdentNameLink(Ident: TIdentifier;
                                       WriteFile: Boolean = False): String;
begin
 assert(assigned(Ident));
 assert(not assigned(Ident.MemberOf));
 assert(not DoNotDocumentIdentifier(Ident));

 if WriteFile then                     //file should also be written?
  begin
   if DoNotDocumentIdentifier(nil, Ident.InFile) then //file is not documented?
    //just show the name of the file
    Result := IdentifierText(Ident.InFile.InternalFileName)
   else
    Result := GetFileNameLink(Ident.InFile);            //add link to file
   Result := Result + '.';                            //add separating dot
  end
 else
  Result := '';
 Result := Result + FDocumentFormats.FPreLinkText +  //write link to identifier
           GetURIOf(Ident) + FDocumentFormats.FMiddleLinkText +
           IdentifierText(Ident.Name) + FDocumentFormats.FPostLinkText;
end;

{Returns a string containing a link to the given identifier inside a
 record-like type (a member of it).
~param Ident       the identifier to link to
~param WriteRecord if the type (also as a link) should be written
~result a string containing a link to the identifier (and the type) }
function TDocumentDoc.GetRecordFieldNameLink(Ident: TIdentifier;
                                         WriteRecord: Boolean = False): String;
begin
 assert(assigned(Ident));
 assert(assigned(Ident.MemberOf));
 assert(not DoNotDocumentIdentifier(Ident));
 assert(not DoNotDocumentIdentifier(Ident.MemberOf));

 if WriteRecord then                 //record-like type should alse be written?
  Result := FDocumentFormats.FPreLinkText +   //add link to record-like type
            GetURIOf(Ident.MemberOf) + FDocumentFormats.FMiddleLinkText +
            IdentifierText(Ident.MemberOf.Name) +
            FDocumentFormats.FPostLinkText + '.'
 else
  Result := '';
 //add link to member of record-like type
 Result := Result + FDocumentFormats.FPreLinkText +
           GetURIOf(Ident) + FDocumentFormats.FMiddleLinkText +
           IdentifierText(Ident.Name) + FDocumentFormats.FPostLinkText;
end;