uicidentdocbuilder.pas

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

   4:  begin
        Desc.Name := 'ResultIfUncommented';
        Desc.Category := 'Comments';
        Desc.Description := 'Create an entry for the result of a function even if it is not commented.';
        Desc.DataType := otBoolean;
        Desc.DefaultValue.BoolData := False;
       end;
 else
  assert(Index >= GetOptionCount);       //invalid index!
  raise EInvalidOption.Create('Invalid index for option supplied!');
 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 TICIdentDocBuilder.GetOption(Index: Cardinal): TOptionValue;
begin
 case Index of                              //depending on index of option
   0: Result.SetData := SetToOption(FCommentsSectionsFilter,  //get the value
                                    SizeOf(FCommentsSectionsFilter));
   1: Result.SetData := SetToOption(FIdentifierSectionsFilter,
                                    SizeOf(FIdentifierSectionsFilter));
   2: Result.SetData := SetToOption(FFileSectionsFilter,
                                    SizeOf(FFileSectionsFilter));
   3: Result.BoolData := FParameterListIfUncommented;
   4: Result.BoolData := FResultIfUncommented;
 else
  assert(Index >= GetOptionCount);          //invalid index!
  raise EInvalidOption.Create('Invalid index for option supplied!');
 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 TICIdentDocBuilder.SetOption(Index: Cardinal; Value: TOptionValue);
begin
 case Index of                         //depending on index of option
  0: OptionToSet(Value.SetData, FCommentsSectionsFilter,    //set the value
                                SizeOf(FCommentsSectionsFilter));
  1: OptionToSet(Value.SetData, FIdentifierSectionsFilter,
                                SizeOf(FIdentifierSectionsFilter));
  2: OptionToSet(Value.SetData, FFileSectionsFilter,
                                SizeOf(FFileSectionsFilter));
  3:  FParameterListIfUncommented := Value.BoolData;
  4:  FResultIfUncommented := Value.BoolData;
 else
  assert(Index >= GetOptionCount);     //invalid index!
  raise EInvalidOption.Create('Invalid index for option supplied!');
 end;
end;



{Returns an object to edit the options of the parser of the comments.
 The object must not be freed.
~result an object to edit the options of the parser of comments }
function TICIdentDocBuilder.GetOptions: TOptionWrapper;
begin
 if not assigned(FOptionAccessor) then          //accessor does not exist yet?
  FOptionAccessor := TICIdentDocBuilderOptionWrapper.Create(Self);  //create it
 Result := FOptionAccessor;                     //return the wrapper
end;




{Resets the builder of documentation to generate new documentation. }
procedure TICIdentDocBuilder.ResetForNewGeneration;
begin
                         //nothing to reset in this class
end;






{Called when a reference to an implemented interface is found in the
 declaration but the interface has not been implemented by the class. This
 is an inconsistency within the data that may indicate the the source can not
 be compiled or the parser is faulty.
~param Sender        the sender of the event, the assembler of delcarations
~param InterfaceName the name of the interface that has been referenced
                     inside but not implemented by a class
~param Position      the position where the unknown interface has been used,
                     either a method or a property
~param FromMethod    whether the interface has been referenced to rename one of
                     its methods, instead of aliases its implementation to a
                     property }
procedure TICIdentDocBuilder.HandleUnknownInterface(
                                               Sender: TICDeclarationAssembler;
                                               const InterfaceName: String;
                                               Position: TIdentifier;
                                               FromMethod: Boolean);
begin
 if FromMethod then                   //add the message
  AddMessage(idbmInterfaceOfMethodNotImplemented,
             Format(DocumentationTexts[dtInterfaceOfMethodNotImplemented].T,
                    [InterfaceName]),
             Position, nil)
 else
  AddMessage(idbmImplementedInterfaceOfPropertyDoesNotMatch,
             Format(DocumentationTexts[
                               dtImplementedInterfaceOfPropertyDoesNotMatch].T,
                    [InterfaceName]),
             Position, nil);
end;

{Adds the message to the geneator.
~param Msg        the kind of the message to be added
~param Text       the text of the message
~param Identifier the identifier at which the message has been generated, nil
                  if at a file
~param TheFile    the file at which the message has been generated, nil if at
                  an identifier }
procedure TICIdentDocBuilder.AddMessage(Msg: TIdentDocBuilderMessages;
                                        const Text: String;
                                        Identifier: TIdentifier;
                                        TheFile: TPascalFile);
begin                    //just add the message to the generator
 FGenerator.AddIdentifierMessage(FIdentDocBuilderMessagesID, Ord(Msg), Text,
                                 Identifier, TheFile);
end;





{Adds the name of the identifier to the node.
~param IdentifierName the name (and path) of the identifier to add
~param AddTo          the node to add the name to }
procedure TICIdentDocBuilder.AddIdentifierText(const IdentifierName: String;
                                               AddTo: TICNCompound);
begin                      //just add a node with the name of the identifier
 AddTo.AppendNode(TICNPascalCode.CreatePascalCode(AddTo.Owner,
                                                  icpcIdentifier,
                                                  IdentifierName));
end;

{Adds the reserved word to the node.
~param ReservedWord the reserved word(s?) to add
~param AddTo        the node to add the reserved word to }
procedure TICIdentDocBuilder.AddReservedWord(const ReservedWord: String;
                                             AddTo: TICNCompound);
begin                      //just add a node with the name of the reserved word
 AddTo.AppendNode(TICNPascalCode.CreatePascalCode(AddTo.Owner,
                                                  icpcReservedWord,
                                                  ReservedWord));
end;




{Adds a link to the given file.
~param TheFile the file to link to
~param AddTo   the node to add the link to }
procedure TICIdentDocBuilder.AddFileLink(TheFile: TPascalFile;
                                         AddTo: TICNCompound);
begin
 Assert(Assigned(TheFile));
 Assert(not FGenerator.DoNotDocumentFile(TheFile));

 //just add a link to the file as a node
 AddTo.AppendNode(TICNPascalLink.CreateLink(AddTo.Owner, nil, TheFile));
end;


{Adds a link to the given identifier. The identifier can't be declared inside a
 record-like type (use ~[link .AddRecordFieldLink] for that) but must be
 top-level declared inside the file.
~param Ident         the identifier to link to
~param AddTo         the node to add the link to
~param AddLinkToFile whether the file should also be linked to }
procedure TICIdentDocBuilder.AddIdentifierLink(Ident: TIdentifier;
                                               AddTo: TICNCompound;
                                               AddLinkToFile: Boolean = False);
begin
 Assert(Assigned(Ident));
 Assert(not Assigned(Ident.MemberOf));
 Assert(not FGenerator.DoNotDocumentIdentifier(Ident));

 if AddLinkToFile then                    //link to file should also be added?
  begin
   AddFileLink(Ident.InFile, AddTo);                        //add link to file
   AddTo.AppendNode(TICNText.CreateText(AddTo.Owner, '.')); //+ separating dot
  end;

 //add link to identifier
 AddTo.AppendNode(TICNPascalLink.CreateLink(AddTo.Owner, Ident, nil));
end;

{Adds a link to the given identifier inside (member of) a record-like type.
~param Ident         the identifier/member to link to
~param AddTo         the node to add the link to
~param AddRecordLink whether the record-like type should also be linked to }
procedure TICIdentDocBuilder.AddRecordFieldLink(Ident: TIdentifier;
                                               AddTo: TICNCompound;
                                               AddRecordLink: Boolean = False);
begin
 Assert(Assigned(Ident));
 Assert(Assigned(Ident.MemberOf));
 Assert(not FGenerator.DoNotDocumentIdentifier(Ident));
 Assert(not FGenerator.DoNotDocumentIdentifier(Ident.MemberOf));

 if AddRecordLink then         //link to record-like type should also be added?
  begin                                   //add link to record-like type
   AddTo.AppendNode(TICNPascalLink.CreateLink(AddTo.Owner,
                                              Ident.MemberOf, nil));
   AddTo.AppendNode(TICNText.CreateText(AddTo.Owner, '.')); //+ separating dot
  end;

 //add link to member of record-like type
 AddTo.AppendNode(TICNPascalLink.CreateLink(AddTo.Owner, Ident, nil));
end;
























{Adds the list of all implemented interfaces.
~param Ident the identifier (of a class) whose implemented interfaces should be
             added as a list of links
~param First if here the first interface will be added
~param AddTo the node to add the list to
~result whether the added list not empty anymore }
function TICIdentDocBuilder.AddInterfaceLinks(Ident: TRecordType;
                                              First: Boolean;
                                              AddTo: TICNCompound): Boolean;
var      i                 :Integer;   //counter through implemented interfaces
         Interf            :TIdentifier; //an implemented interface
begin
 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 interface known and documented
   if assigned(TIdentType(Interf).TheType) and
      not FGenerator.DoNotDocumentIdentifier(TIdentType(Interf).TheType) then
    begin
     if First then                                 //the first one?
      First := False                                 //next is not the first
     else
      AddTo.AppendText(', ');                        //add a separator
     AddIdentifierLink(TIdentType(Interf).TheType, AddTo); //add link
    end;
  end;
 Result := not First;              //whether at least one interface was added
end;

{Adds the list of all in parent-classes implemented interfaces.
~param Ident the identifier (of a class) whose list of all interfaces
             implemented by its ancestors should be added as links
~param AddTo the node to add the list to }
procedure TICIdentDocBuilder.AddParentInterfaceLinks(Ident: TRecordType;
                                                     AddTo: TICNCompound);
var       First             :Boolean; //whether no interface has been added yet
begin
 First := True;                   //no interface added so far
 Ident := Ident.GetParent;        //start with its parent
 while assigned(Ident) do         //while (known) ancestors
  begin
   //get list of this class, some added?
   if AddInterfaceLinks(Ident, First, AddTo) then
    First := False;                   //next won't be the first anymore

   Ident := Ident.GetParent;      //get the parent class of the class
  end;
end;


{Adds the list of the direct descendants of the record-like type.
~param Ident the identifier whose descendants should be added
~param AddTo the node to add the list to }
procedure TICIdentDocBuilder.AddDirectDescendantList(Ident: TRecordType;
                                                     AddTo: TICNCompound);
var       First             :Boolean;     //if it is the first added identifier
          i                 :Integer;     //counter through sub-classes
          SubClass          :TRecordType; //each of the sub-classes
begin
 assert(Ident.Kind in [rkObject, rkClass, rkInterface]);

 First := True;                                //next identifier is the first
 for i := 0 to Ident.Children.Count - 1 do     //for each known direct subclass
  begin
   SubClass := TRecordType(Ident.Children[i]);    //get the subclass

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