updfdoc.pas

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

         Desc.Category := 'Generation';
         Desc.Description := 'Disables compression of the PDF file (raises the size by about 66%).';
         Desc.DataType := otBoolean;
         Desc.DefaultValue.BoolData := False;
        end;
     1: begin
         Desc.Name := 'FileName';
         Desc.Category := '';
         Desc.Description := 'The name of the PDF File to be generated.';
         Desc.DataType := otString;
         Desc.DefaultValue.StrData := DefaultPDFFileName;
        end;
     2: begin
         Desc.Name := 'TableOfContentsDetailLevel';
         Desc.Category := 'Generation';
         Desc.Description := 'To what sub-level topics will be listed in the table of contents.';
         Desc.DataType := otInteger;
         Desc.DefaultValue.IntData := High(TTableOfContentsDetailLevel);
         Desc.MinInt := Low(TTableOfContentsDetailLevel);
         Desc.MaxInt := High(TTableOfContentsDetailLevel);
        end;
   else
    assert(Index >= GetOptionCount);
    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 TPDFDoc.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 := FDisablePDFCompression; //get the value
     1: Result.StrData := FPDFFileName;
     2: Result.IntData := FTableOfContentsDetailLevel;
   else
    assert(Index >= GetOptionCount);
    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 TPDFDoc.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: FDisablePDFCompression := Value.BoolData; //set the value
    1: FPDFFileName := Trim(Value.StrData);
    2: if Value.IntData > High(FTableOfContentsDetailLevel) then
        FTableOfContentsDetailLevel := High(FTableOfContentsDetailLevel)
       else
        if Value.IntData >= Low(FTableOfContentsDetailLevel) then
         FTableOfContentsDetailLevel := Value.IntData;
  else
   assert(Index >= GetOptionCount);
   raise EInvalidOption.Create('Invalid index for option supplied!');
  end;
end;



{Returns the capabilities of this class of the generators.
~result the capabilities of this class of the generators }
class function TPDFDoc.Capabilities: TGeneratorCapabilities;
begin
 Result := inherited Capabilities + [gcGUIHelp];
end;































































{Gets the links to the generated files by ~[link WriteFileTreeFiles].
~result a text including links to the generated files }
function TPDFDoc.GetFileListFileLinks: String;
begin
 Result := InternFormatCharacter + InternFormatParagraph; //start new paragraph
 if GenerateXFigFiles then                 //Xfig files have been generated?
  //generate a link to the Xfig file
  Result := Result + InternFormatCharacter + InternFormatExternLink +
                     'http://www.xfig.org/' + InternFormatEndCharacter +
                     Localize(dtDocumentationLinkXFigFiles) +
                     InternFormatEndCharacter +
                     ': ' +
                     InternFormatCharacter + InternFormatFileLink +
                     FFileTreeFileBaseName + '.fig' +
                     InternFormatEndCharacter +
                     FFileTreeFileBaseName + '.fig' +
                     InternFormatEndCharacter;
 if GenerateWMFFiles then                  //WMF files have been generated?
  begin
   if GenerateXFigFiles then                 //also Xfig files?
    //start a new line
    Result := Result + InternFormatCharacter + InternFormatNewLine;

   //generate a link to the WMF file
   Result := Result + Localize(dtDocumentationLinkWMFFiles) + ': ' +
                      InternFormatCharacter + InternFormatFileLink +
                      FFileTreeFileBaseName + '.wmf' +
                      InternFormatEndCharacter +
                      FFileTreeFileBaseName + '.wmf' +
                      InternFormatEndCharacter;
  end;
end;

{Writes the list of files.
~param Text the text (by ~[link GetFileListText]) of the list of files }
procedure TPDFDoc.WriteFileList(const Text: String);
begin
 //create a new section for the list of files
 WriteNewSection(Localize(dtDocumentationFilesListTopic), 'FileList');

 WriteParsedText(InternFormatCharacter + InternFormatAlignLeft +
                 Text);          //write the list of the files
end;








{Write the documentation about all identifiers of the given kind in the file.
~param AFile     the file whose identifiers to write
~param FileTopic the internal name of the documentation of the file
~param WriteType the kind of identifiers to write }
procedure TPDFDoc.WriteVarConstFuncTypes(AFile: TPascalFile;
                                         const FileTopic: String;
                                         WriteType: TWriteKind);

          //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 prefixes of the internal name of the pages of the lists of
          //the different kinds of identifiers in files
          TopicDeclName: array[TWriteKind] of String =
             ('Variables',       'ThreadVariables', 'Constants',
              'ResourceStrings', 'Functions',       'Types');


var      AClass     :TIdentifierClass;    //class the identifiers have to be
         List       :TIdentifierList;     //list of the identifiers in the file
         i          :Integer;             //counter through the lists
         Ident      :TIdentifier;         //each identifier
         Comment    :String;              //the documentation of identifiers
         Port       :TIdentPortabilities; //their portability issues
         Dummy      :String;              //not used
         Text       :String;              //the text with intermediate code
begin
 List := TIdentifierList.Create;         //create list for matching identifiers
 try
   AClass := DeclTypeClass[WriteType];
   for i := 0 to AFile.Idents.Count - 1 do //for all identifiers in the file
    begin
     Ident := AFile.Idents[i];               //get it
     if (((Ident is AClass) and                //if it matches the criteria
          (not (WriteType in [wkVar, wkThreadVar]) or
           (TVariable(Ident).IsThreadVar = (WriteType = wkThreadVar)))) or
         ((WriteType = wkConst) and (Ident is TEnumTypeItem))) and
        not DoNotDocumentIdentifier(Ident) then //documented?
      List.AddIdent(Ident);                       //add it to the list
    end;

   if not List.IsEmpty then                //some identifiers found?
    begin
     //write topic of the identifiers
     WriteNewSubSection(Localize(DeclName[WriteType]),
                        FileTopic + '.' + TopicDeclName[WriteType]);

     List.Sort;                              //sort the list
     for i := 0 to List.Count - 1 do         //for each identifier
      begin
       Ident := List[i];                       //get it

       if not (Ident is TRecordType) then      //not special record-like type?
        begin
         //set identifier to get its documentation
         SetCommentIdent(Ident, AFile);
         Dummy := '';
         Comment := GetIdentComment(Dummy);      //get its documentation

         //start the topic of the documentation of the identifier
         WriteNewItemSection(Ident.Name, GetURIOf(Ident));

         //get scope and portability issues
         Port := Ident.Portability;
         if FDeprecatedList.IsIn(Ident) then
          Include(Port, ipDeprecated);
         Text := GetScope(Ident.Scope) + GetPortabilityIssues(Port) + ' ';

         //if it is a type, write also its name
         if (WriteType = wkSimpleType) {and not (Ident is TRecordType)} then
          Text := Text + Ident.Name +  ' = ';

         //write the declaration of the identifier
         WriteParsedText(InternFormatCharacter + InternFormatAlignLeft +
                         Text +
                         Ident.GetDescriptionString(Self, Ident) +
                         InternFormatCharacter + InternFormatParagraph +
                         InternFormatCharacter + InternFormatAlignBlock +
                         Comment, True); //and end the paragraph
        end
       else
        begin
         //write the topic of the link to the documentation
         WriteNewItemSection(IdentifierText(Ident.Name),
                             GetURIOf(Ident) + '.unused');

         //just write a link to the documentation of the record-like type
         WriteParsedText(InternFormatCharacter + InternFormatAlignLeft +
                         Localize(dtDocumentationLinkRecordLikePre) +
                         InternFormatCharacter + InternFormatLink +
                         DescFilePreFix[TRecordType(Ident).Kind] + 'Part' +
                         InternFormatEndCharacter +
                         Localize(dtDocumentationLinkRecordLikeChapterPrefix) +
                         Localize(Plurals[TRecordType(Ident).Kind]) +
                         InternFormatEndCharacter +
                         Localize(dtDocumentationLinkRecordLikeMiddle) +
                         GetIdentNameLink(Ident) +
                         Localize(dtDocumentationLinkRecordLikePost) +
                         InternFormatCharacter + InternFormatParagraph,
                         False);          
        end;
      end; //for i := 0 to List.Count - 1
    end; //if not List.IsEmpty
 finally
  List.RemoveAll(False);              //free the list (without the identifiers)
  List.Free;
 end;
end;





{Writes the documentation about the file.
~param AFile the file whose documentation should be written }
procedure TPDFDoc.WriteFileDocumentation(AFile: TPascalFile);
var       TopicName       :String;     //name of the page of the file
          Dummy           :String;     //not used
          WType           :TWriteKind; //all kinds of identifiers
begin
 TopicName := GetURIOf(nil, AFile);    //get the internal name of the file

 //write topic of the documentation of the file
 WriteNewSection(FileTypeNames[AFile.FileType] + ' ' +
                 IdentifierText(AFile.InternalFileName), TopicName);

 SetCommentIdent(nil, AFile);          //set the file to get the comment
 Dummy := '';
 //get and write the documentation of the file
 WriteParsedText(InternFormatCharacter + InternFormatAlignLeft +
                 GetFileComment(Dummy), True);

 //write documentation of all kinds of identifiers in the file
 for WType := low(WType) to high(WType) do
  WriteVarConstFuncTypes(AFile, TopicName, WType);
end;