updfdoc.pas

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

{Gets the text of an indentation by the given depth.
~param Indent the depth of the class in the inheritance tree
~result an indentation by the given depth }
function TPDFDoc.ClassListIndent(Indent: Integer): String;
begin
 //indent by a multiple of the width of 7 spaces
 Result := InternFormatCharacter + InternFormatIndent + Chr(7 * Indent);
end;

{Write the links to the generated files by ~[link WriteClassesTreeFiles].
~param Kind the kind of the record-like types (record/class/interface/...)
~result a text including links to the generated files }
function TPDFDoc.ClassListFileLinks(Kind: TRecordKind): String;
begin
 //start a new paragraph
 Result := InternFormatCharacter + InternFormatParagraph;
 if GenerateXFigFiles then       //Xfig files have been written?
  //return a link to the file
  Result := Result + InternFormatCharacter + InternFormatExternLink +
                     'http://www.xfig.org/' + InternFormatEndCharacter +
                     Localize(dtDocumentationLinkXFigFiles) +
                     InternFormatEndCharacter +
                     ': ' +
                     InternFormatCharacter + InternFormatFileLink +
                     FClassTreeFileBaseName[Kind] + '.fig' +
                     InternFormatEndCharacter +
                     FClassTreeFileBaseName[Kind] + '.fig' +
                     InternFormatEndCharacter;
 if GenerateWMFFiles then            //WMF files have been written?
  begin
   if GenerateXFigFiles then            //Xfig files have also been written?
    //insert a separator between links
    Result := Result + InternFormatCharacter + InternFormatNewLine;

   //return a link to the file
   Result := Result + Localize(dtDocumentationLinkWMFFiles) + ': ' +
                      InternFormatCharacter + InternFormatFileLink +
                      FClassTreeFileBaseName[Kind] + '.wmf' +
                      InternFormatEndCharacter +
                      FClassTreeFileBaseName[Kind] + '.wmf' +
                      InternFormatEndCharacter;
  end;
end;

{Writes the hierarchy of the kind of the record-like types.
~param Kind the kind of the record-like types (record/class/interface/...)
~param Text the text (by ~[link GetClassListText]) of the tree of classes }
procedure TPDFDoc.WriteClassList(Kind: TRecordKind; const Text: String);
begin
 //create the topic for the hierarchy of the kind of the record-like types
 WriteNewSection(Localize(dtDocumentationClassListHeaderPrefix) +
                 Localize(Plurals[Kind]), DescFilePreFix[Kind] + 'List');

 WriteParsedText(InternFormatCharacter + InternFormatAlignLeft +
                 Text);               //write the hierarchy of the classes
end;









{Writes the documentation of all members of a certain kind of a record-like
 type.
~param Kind  the kind of members to write documentation about
~param Ident the record-like type containing the members }
procedure TPDFDoc.WriteMembers(Kind: TMemberKind; Ident: TRecordType);

          //internal names of the lists
const     KindNames: array[TMemberKind] of String =
                      ('Fields', 'Properties', 'Methods');
          //titles of the lists
          KindTitles: array[TMemberKind] of TDocumentationTexts =
                      (dtDocumentationClassMembersFields,
                       dtDocumentationClassMembersProperties,
                       dtDocumentationClassMembersMethods);

 {Gets the list of members in the record-like type.
 ~param List the list to add the members to }
 procedure GetList(List: TIdentifierList);
 var       AClass :TIdentifierClass;         //the class the members have to be
           i      :Integer;                  //counter through all members
           One    :TIdentifier;              //each member
 begin
  AClass := MemberKindClasses[Kind];
  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 AClass) and not DoNotDocumentIdentifier(One) then
     List.AddIdent(One);                         //add it to the list
   end;
 end;


 {Generates the documentation about all identifiers in the list.
 ~param List the list of identifiers to generate documentation about }
 procedure WriteMemberListDocumentation(List: TIdentifierList);
 var       i         :Integer;       //counter through all members in the list
           Member    :TIdentifier;   //each member in the list
           Dummy     :String;        //not used
           Comment   :String;        //documentation about the member
           Text      :String;        //the text with intermediate code
           Port      :TIdentPortabilities; //portability issues of the member
 begin
  List.Sort;                         //sort the list
  for i := 0 to List.Count - 1 do    //for each member of the list
   begin
    Member := List[i];                      //get it

    SetCommentIdent(Member, Member.InFile); //set member for comment
    Dummy := '';
    Comment := GetIdentComment(Dummy);      //get the comment

    //start a topic for the member
    WriteNewItemSection(IdentifierText(Member.Name), GetURIOf(Member));

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

//    if (Kind = cwkMethods) and
//       (faAbstract in TFunction(Member).Attributes) then
//     Text := Text + FCommentFormats.FAbstractIconText;

    //write its declaration and documentation
    WriteParsedText(InternFormatCharacter + InternFormatAlignLeft +
                    Text + ' ' +
                    Member.GetDescriptionString(Self, Ident) +
                    InternFormatCharacter + InternFormatParagraph +
                    InternFormatCharacter + InternFormatAlignBlock +
                    Comment);
   end; //for i := 0 to List.Count - 1
 end;


 {Writes the list of inherited members of the kind in the record-like type.
 ~param AllList   the list containing all inherited members
 ~param TopicName base name of the topics of the lists }
 procedure WriteInheritedLists(List: TIdentifierList; const TopicName: String);
 var       Member             :TIdentifier;  //each member
           Text               :String;       //the text with intermediate code

  {Writes the current member.
  ~param MayWriteType if the record-like type the member is in may be written }
  procedure WriteMember(MayWriteType: Boolean);
  var       Port       :TIdentPortabilities; //portability issues of the member
  begin
   Text := Text + GetScope(Member.Scope);    //add scope
   Port := Member.Portability;
   if FDeprecatedList.IsIn(Member) then      //and its portability issues
    Include(Port, ipDeprecated);
   Text := Text + GetPortabilityIssues(Port);

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

   if Kind = mkMethod then                 //if it is a method
    begin
     //if it is abstract, write an indicating icon
     if faAbstract in TFunction(Member).Attributes then
      Text := Text + FCommentFormats.FAbstractIconText;
     //if it is a class method, indicate this by writing "class"
     if faClassMethod in TFunction(Member).Attributes then
      Text := Text + ReservedWord('class') + ' ';
     //if it is a con-/destructor, indicate this by writing this
     if TFunction(Member).FuncKind in [fkConstructor, fkDestructor] then
      Text := Text + ReservedWord(FuncNames[TFunction(Member).FuncKind]) + ' ';
    end;

   //add a link to the member
   Text := Text + GetRecordFieldNameLink(Member, MayWriteType and
                                                 (Member.MemberOf <> Ident));
  end;

           //record-like type of the previous member
 var       LastRec            :TRecordType;
           i                  :Integer;     //counter through all members
 begin
  //write a topic for the list of identifiers
  WriteNewItemSection(Localize(dtDocumentationClassInheritedMembersPrefix) +
                      Localize(KindTitles[Kind]),
                      TopicName + '.Inherited' + KindNames[Kind]);

  Text := '';                         //no list so far
  List.SortTo(Ident);                 //sort the list by the record-like types
  LastRec := nil;                     //no member (and record-like type) so far
  for i := 0 to List.Count - 1 do     //for each member
   begin
    Member := List[i];                //get it

    if LastRec <> Member.MemberOf then //new record-like type?
     begin
      if assigned(LastRec) then           //not first member?
       //end previous list
       Text := Text + InternFormatCharacter + InternFormatNewLine;
      LastRec := Member.MemberOf;         //save record-like type
      //start list of members in this record-like type
      Text := Text + InternFormatCharacter + InternFormatBold +
                     Localize(KindTitles[Kind]) +
                     Localize(dtDocumentationClassInheritedInMiddle) +
                     LastRec.Name +
                     InternFormatEndCharacter +
                     InternFormatCharacter + InternFormatNewLine;
     end
    else
     Text := Text + ', ';                 //add a separator

    WriteMember(False);                 //add link to the member
   end;

  //write the list
  WriteParsedText(InternFormatCharacter + InternFormatAlignLeft +
                  Text + InternFormatCharacter + InternFormatNewLine);



  //more than one parent class known?
  if assigned(Ident.GetParent.GetParent()) then
   begin
    //start a topic for the alphabetically sorted list
    WriteNewItemSection(Localize(dtDocumentationClassInheritedMembersPrefix) +
                        Localize(KindTitles[Kind]) +
                        Localize(dtDocumentationClassMembersByNamePostfix),
                        TopicName + '.Inherited' + KindNames[Kind] + 'Alpha');

    Text := '';                         //no list so far
    List.Sort;                          //sort list alphabetically
    for i := 0 to List.Count - 1 do     //for each member
     begin
      if i <> 0 then                      //not the first entry?
       Text := Text + ', ';                 //add a separator

      Member := List[i];                  //get it
      WriteMember(True);                  //and add link to the member
     end;

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


var       TopicName             :String;          //base name of topics
          //list of members in this record-like type
          List                  :TIdentifierList;
          Parent                :TRecordType;     //parent class
          //list of inherited members
          AllList               :TIdentifierList;
begin
 List := TIdentifierList.Create;             //create list for the members
 try
   TopicName := GetURIOf(Ident);             //get base name of the topics

   GetList(List);                            //get members in the type
   if not List.IsEmpty then                  //some members found?
    begin
     //write topic of the list of the members
     WriteNewSubSection(Localize(KindTitles[Kind]),
                        TopicName + '.' + KindNames[Kind]);

     //write the documentation of the members
     WriteMemberListDocumentation(List);
    end;


   Parent := Ident.GetParent;                //get parent class
   if assigned(Parent) then                  //has a known parent class?
    begin
     //create list for inherited members
     AllList := TIdentifierList.Create;
     try                                       //get inherited members
       GetInheritedList(Parent, AllList, MemberKindClasses[Kind]);
       if not AllList.IsEmpty then             //some inherited found?
        begin
         if List.IsEmpty then                    //no members in this type?
          //write the topic of the members now
          WriteNewSubSection(Localize(KindTitles[Kind]),
                             TopicName + '.' + KindNames[Kind]);

         //write lists of inherited members
         WriteInheritedLists(AllList, TopicName);
        end;
     finally
      AllList.RemoveAll(False);            //don't free members
      AllList.Free;                        //free list of members in this type
     end;
    end; //if assigned(Parent)
 finally
  List.RemoveAll(False);                 //free list of inherited members
  List.Free;
 end;
end;


{Writes the documentation of the record-like type.
~param Ident the record-like type whose data should be written }
procedure TPDFDoc.WriteClassDocumentation(Ident: TRecordType);
var       Dummy         :String;         //not used
          Comment       :String;         //comment of the file
          Text          :String;         //the text with intermediate code
          Interf        :String;         //implemented interfaces
          PInterf       :String;     //by parent classes implemented interfaces
          SubClasses    :String;         //direct sub-classes
          Implementors  :String;         //implementing classes of interface
          i             :Integer;        //general counter
          User          :TIdentifier;    //all using identifiers
          First         :Boolean;        //if it is the first using identifier
begin
 SetCommentIdent(Ident, Ident.InFile);   //set record-like type for comment
 Dummy := '';
 Comment := GetIdentComment(Dummy);      //get its comment

 //start a new topic for the documentation of the record-like type
 WriteNewSection(RecordKindNames[Ident.Kind] + ' ' + Ident.Name,
                 GetURIOf(Ident));