uicidentdocbuilder.pas

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

{Adds the list of the classes implementing the interface.
~param Ident the interface whose implementing classes should be added
~param AddTo the node to add the list to }
procedure TICIdentDocBuilder.AddImplementingClassesList(Ident: TRecordType;
                                                        AddTo: TICNCompound);
var       First             :Boolean;    //if it is the first added identifier
          i                 :Integer;    //counter through implementing classes
          Implementor       :TRecordType; //each of the implementing classes
begin
 assert(Ident.Kind = rkInterface);

 First := True;                                //next identifier is the first
 for i := 0 to Ident.Implementing.Count - 1 do //for each implementing class
  begin
   Implementor := TRecordType(Ident.Implementing[i]); //get implementing class

   if not FGenerator.DoNotDocumentIdentifier(Implementor) then //is documented?
    begin
     if First then                                      //the first one?
      First := False                                      //next is not first
     else
      AddTo.AppendText(', ');                             //add a separator
     AddIdentifierLink(Implementor, AddTo);             //add link to subclass
    end;
  end;
end;




{Gets the list of documented methods overriding the method.
~param Method  the method to which a list of overriding methods is searched
~param RecType the record-like type the method is defined in
~param List    the list were overriding methods are added to }
procedure TICIdentDocBuilder.GetOverridingMethods(Method: TFunction;
                                                  RecType: TRecordType;
                                                  List: TIdentifierList);
var       i                 :Integer;  //counter through all direct descendants
          Child             :TRecordType; //each direct known descendant
          Member            :TIdentifier; //the overriding method
begin
 for i := 0 to RecType.Children.Count - 1 do //for each direct descendant
  begin
   assert(RecType.Children[i] is TRecordType);
   Child := TRecordType(RecType.Children[i]);  //get it

   //search the overriding method
   Member := Child.IdentList.GetIdentByName(Method.Name);
   if Member is TFunction then                 //found and is a method?
    begin
     //add link to the method
     if not FGenerator.DoNotDocumentIdentifier(Member) then //documented?
      List.AddIdent(Member);                       //add it

     GetOverridingMethods(TFunction(Member), Child, List); //add of descendants
    end
   else
    GetOverridingMethods(Method, Child, List);   //search its descendants
  end; //for i := 0 to RecType.Children.Count - 1
end;


{Adds the list of links to the methods overriding the given one.
~param Method  the method to which a list of overriding methods is searched
~param RecType the record-like type the method is defined in
~param AddTo   the node to add the list to }
procedure TICIdentDocBuilder.AddOverridingMethods(Method: TFunction;
                                                  RecType: TRecordType;
                                                  AddTo: TICNCompound);
var       List              :TIdentifierList; //list of overriding methods
          IdentTopic        :TICNTopicForIdentifier; //topic of the list
          i                 :Integer;  //counter through all overriding methods
begin
 List := TIdentifierList.Create;       //create list for overriding methods
 try
   GetOverridingMethods(Method, RecType, List); //get all overriding methods

   if not List.IsEmpty then                     //some method found?
    begin
     //create the topic for the list
     IdentTopic := TICNTopicForIdentifier.CreateTopic(AddTo.Owner,
                                                      ictiMethodOverriding);
     AddTo.AppendNode(IdentTopic);

     for i := 0 to List.Count - 1 do               //for each overriding method
      begin
       assert(List[i] is TFunction);
       if i <> 0 then                                 //not first method?
        IdentTopic.AppendText(', ');                    //add a separator

       AddRecordFieldLink(List[i], IdentTopic, True); //add link to the method
      end;
    end;
 finally
  List.RemoveAll(False);               //don't free the methods
  List.Free;                           //free the list
 end;
end;

{Adds a list of all abstract methods in the class, i.e. all not yet implemented
 abstract methods.
~param AClass the class to get all abstract methods of
~param AddTo  the node to add the list to }
procedure TICIdentDocBuilder.AddStillAbstractMethods(AClass: TRecordType;
                                                     AddTo: TICNCompound);
var       List              :TIdentifierList; //list of still abstract methods
          TheClass          :TRecordType;   //the original given class to test
          i                 :Integer;   //counter through all methods in AClass
          Ident             :TIdentifier;   //all members of AClass
begin
 if AClass.Kind in RecordKindCanBeAbstract then //can have abstract methods?
  begin
   List := TIdentifierList.Create;       //create list for abstract methods
   try

     TheClass := AClass;                 //save the class to test
     repeat

       //check each method whether it is abstract
       for i := AClass.IdentList.Count - 1 downto 0 do
        begin
         Ident := AClass.IdentList[i];       //get identifier
         if (Ident is TFunction) and         //is a method and it is abstract?
            (faAbstract in TFunction(Ident).Attributes) and
            //it is still abstract in the class?
            TFunction(Ident).StillAbstractIn(TheClass) then
          List.AddIdent(Ident);                //add the still abstract method
        end;

       AClass := AClass.GetParent;         //get the parent class
     until not assigned(AClass);         //until all abstract methods added


     for i := List.Count - 1 downto 0 do //for each added abstract method
      begin
       Ident := List[i];                   //get it
       assert(assigned(Ident.MemberOf));

       if i <> List.Count - 1 then         //not the first abstract method?
        AddTo.AppendText(', ');              //add a separator

       //add link to the method or just its name
       if FGenerator.DoNotDocumentIdentifier(Ident) then
        AddIdentifierText(Ident.MemberOf.Name + '.' + Ident.Name, AddTo)
       else
        AddRecordFieldLink(Ident, AddTo, Ident.MemberOf <> TheClass)
      end;

   finally
    List.RemoveAll(False);               //don't free the methods
    List.Free;                           //but free the list
   end;
  end; //if AClass.Kind in RecordKindCanBeAbstract
end;














{Adds the inheritance list of the record-like type.
~param Ident the class whose inheritance list should be returned
~param AddTo the node to add the list to }
procedure TICIdentDocBuilder.AddAncestorList(Ident: TRecordType;
                                             AddTo: TICNCompound);

 {Adds a token of the list.
 ~param Token the token to be added }
 procedure AddToken(Token: TICAncestorListToken);
 begin                        //create a node for the token and add it
  AddTo.AppendNode(TICNTokenAncestorList.CreateAncestorListToken(AddTo.Owner,
                                                                 Token));
 end;

 {Adds the class and all parent classes (ancestors) to the node.
 ~param Parent the class to add to the list }
 procedure AddParent(Parent: TRecordType);
 var       ItsParent       :TRecordType;   //the parent of this identifier
           NotDocumented   :Boolean;       //whether parent is not documented
           Strong          :TICNTextStyle; //to format the current class strong
 begin
  if assigned(Parent) then                 //identifier known?
   begin
    assert((Parent = Ident) or
           not FGenerator.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?
                       FGenerator.DoNotDocumentIdentifier(ItsParent);
      if NotDocumented then
       ItsParent := nil;                         //end ancestor list here

      AddParent(ItsParent);                    //and add it to node
      if not assigned(ItsParent) then          //parent not known?
       begin
        if NotDocumented then                    //because it isn't documented?
         AddToken(icaltMissing)        //indicate that some entries are missing
        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
            begin
             //add an entry for it and indicate that
             AddToken(icaltMissing);              //some entries may be missing
             AddIdentifierText(Parent.IdentParent.DefIdent, AddTo);
             AddToken(icaltArrow);
            end;
          end
         else
          begin                        //just add the name of the parent class
           AddIdentifierText(Parent.IdentParent.DefIdent, AddTo);
           AddToken(icaltArrow);
          end;
       end; //if not assigned(ItsParent)
     end; //if assigned(Parent.IdentParent)

    if Parent = Ident then                          //is the final identifier?
     begin
      AddToken(icaltFinalPre);                        //make entry strong
      Strong := TICNTextStyle.CreateStyle(AddTo.Owner, ictsStrong);
      AddTo.AppendNode(Strong);
      AddIdentifierText(Parent.Name, Strong);         //add final entry
      AddToken(icaltFinalPost);
     end
    else
     begin
      AddIdentifierLink(Parent, AddTo);                //add the identifier
      AddToken(icaltArrow);   //add arrow to next class in the inheritance list
     end
   end //if assigned(Parent)
  else
   if Ident.Kind in [rkClass, rkInterface] then     //has default parent?
    begin                              //add entry for the default parent class
     AddTo.AppendText(DocumentationTexts[DefParentClassNameHeader[Ident.Kind]].
                                                                            T);
     AddToken(icaltArrow);
    end;
 end;

begin
 AddParent(Ident);                   //add the inheritance list
end;










{Adds a list of the identifiers as part of the documentation. It is sorted
 to the current record-like type and identifiers are marked with their special
 properties.
~param List   list of the identifiers
~param SortTo the record-like type for which the list should be sorted
~param Kind   the kind of the topic for the list
~param AddTo  the node to add the list to }
procedure TICIdentDocBuilder.AddDocumentationList(List: TIdentifierList;
                                                  SortTo: TRecordType;
                                                  Kind: TICTopicForIdentifier;
                                                  AddTo: TICNCompound);
var       Topic             :TICNTopicForIdentifier; //the topic of the list
          i                 :Integer;     //counter through the list
          Ident             :TIdentifier; //used global identifiers
begin
 List.SortTo(SortTo);                     //sort the list

 Topic := TICNTopicForIdentifier.CreateTopic(AddTo.Owner, Kind);
 AddTo.AppendNode(Topic);                 //create and add topic for the list

 for i := 0 to List.Count - 1 do          //for each identifier
  begin
   Ident := List[i];                        //get it
   if i <> 0 then                           //if not the first
    Topic.AppendText(', ');                   //add a separator

   //add link to the identifier
   if Assigned(Ident.MemberOf) then
    AddRecordFieldLink(Ident, Topic, Ident.MemberOf <> SortTo)
   else
    AddIdentifierLink(Ident, Topic);          //or just the name
  end;
end;



{Adds the list of global identifiers used in the function.
~param Identifier the function whose used global identifiers should be added
~param AddTo      the node to add the list to }
procedure TICIdentDocBuilder.AddFunctionGlobals(Identifier: TFunction;
                                                AddTo: TICNCompound);
var       List              :TIdentifierList; //list of the used identifiers
          i                 :Integer;         //general counter
          Ident             :TIdentifier;     //used global identifiers
begin
 //has list of used identifiers (abstract methods & external functions won't)?
 if assigned(Identifier.UsedIdents) and        //and list not filtered?
    ([isfGlobals, isfCalls] * FIdentifierSectionsFilter <>
     [isfGlobals, isfCalls]) then
  begin
   List := TIdentifierList.Create;        //create list of global identifiers
   try

     //global identifiers should be listed?
     if not (isfGlobals in FIdentifierSectionsFilter) then
      begin
       //for each used global identifier
       for i := 0 to Identifier.UsedIdents.Count - 1 do