ujaddnodes.pas

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

       if Index <> -1 then
        Delete(Text, 1, Index - 1);                      //by deleting them
       assert((Text = '') or (Text[1] > ' '));
      end;

     Index := FirstWhiteSpace(Text);                 //search end of parameter
     if Index = -1 then                              //no end found?
      begin
       if Text <> '' then                              //some parameter found?
        begin
         Parameter := Parameter + Text;                  //add the parameter
         //at least some parameter has been found (this does not end
         Result := True;                                 //the function)
         Text := '';                                     //text was processed
        end;
      end //if Index = -1
     else
      begin
       //does not start with separator of parameters?
       if Index > 1 then
        begin
         Parameter := Parameter + Copy(Text, 1, Index - 1); //add parameter
         Delete(Text, 1, Index - 1);                        //and remove it
         Result := True;                                    //parameter found
         Index := FirstNonWhiteSpace(Text);                 //skip white spaces
         if Index <> -1 then
          Delete(Text, 1, Index - 1)                         //by deleting them
         else
          Text := '';
        end
       else
        begin
         Index := FirstNonWhiteSpace(Text);                 //skip white spaces
         if Index <> -1 then
          Delete(Text, 1, Index - 1)                         //by deleting them
         else
          Text := '';
        end;
       Finished := True;                               //end of parameter found
      end; //else Index = -1
    end //if Text <> ''
   else
    //end of parameter found (no content left in node)
    Finished := True;
  end; //while not Finished

 NextNodeIndex := NodeIndex;             //save back the index of the next node
 ParamStr := Text;                       //and remant of text of the last node
end;

















   { * * *  ***  * * *  ***   TJaddNodeOwner   ***  * * *  ***  * * *  }


{Creates the owner of the nodes and the list for the owned nodes. }
constructor TJaddNodeOwner.Create;
begin
 inherited Create;                           //create the object

 FList := TList.Create;                      //create list of owned nodes
end;

{Frees this object and all owned nodes. }
destructor TJaddNodeOwner.Destroy;
var        i             :Integer;           //counter through owned nodes
begin
 if assigned(FList) then                     //list of node has been created?
  begin
   for i := 0 to FList.Count - 1 do            //free all nodes
    TJaddNode(FList[i]).Free;
   FList.Free;                                 //free the list itself
  end;

 inherited Destroy;                          //free the object
end;


{Adds a node so it is owned (and eventually freed) by this object.
~param Node the new node to be owned and freed by this object }
procedure TJaddNodeOwner.AddNode(Node: TJaddNode);
begin
 assert(assigned(Node));
 assert(FList.IndexOf(Node) = -1);
 FList.Add(Node);                    //add the node to the list of owned nodes
end;




{Checks whether the string is valid to be used as name for a defined text.
~param TextName the name of the text to be checked
~result whether the name of the defined text is valid }
function TJaddNodeOwner.CheckNameOfDefinedText(const TextName: String):
                                                                       Boolean;
var      p             :PChar;      //counter through letters of name
begin
 p := Pointer(TextName);            //check, if name if valid
 while p^ in ['A'..'Z', 'a'..'z', '0'..'9'] do
  Inc(p);
 //all characters valid?
 Result := Integer(p) - Integer(Pointer(TextName)) = length(TextName);
 if not Result then                 //not valid?
  AddMessageFmt(jcmInvalidTextVariableName,     //add a warning message
                'Name for defined text to be inserted is invalid: "%s"!',
                [TextName])
end;

{Returns whether an empty line within the comment is interpreted as the end of
 the current paragraph (a paragraph-break).
~result whether an empty line should end the current paragraph }
function TJaddNodeOwner.EmptyCommentLinesBreakParagraphs: Boolean;
begin
 Result := True;                        //by default it does
end;

{Returns whether links on identifiers with empty text should use a link for
 each part of its used path instead of only a single on all.
~result whether links without text should be split for each component }
function TJaddNodeOwner.UsePathLinks: Boolean;
begin
 Result := True;
end;

{Returns the content of a defined text by its name.
~param TextName the name of the defined text whose value should be returned
~result the content of the defined text, nil if not defined }
function TJaddNodeOwner.GetDefinedText(const TextName: String): TJaddNode;
begin
 Result := nil;                         //by default no text has been defined
end;

{Starts defining a text by its name. The name has to be
 ~[link CheckNameOfDefinedText valid]. After the adding the content of the
 text the method ~[link EndDefineText] must be called (use try..finally).
~param TextName the name of the text that is about to be defined
~result the compound node to which the defined content should be added }
function TJaddNodeOwner.StartDefineText(const TextName: String):
                                                             TJaddNodeCompound;
begin
 Result := nil;                         //by default no text can be defined
end;

{Ends defining a text and registers it so it can be read again.
~param TextName the name of the text that has been defined
~param Text     the content that has been defined for the name }
procedure TJaddNodeOwner.EndDefineText(const TextName: String;
                                       Text: TJaddNodeCompound);
begin
                                        //by default defining does not work
end;

{Returns the value of a variable text at the current position.
~param TextName the name of the variable text to be returned
~param Text     out: the value of the variable text at the current possion
~result whether the name of the variable text was known and its value returned
        in the parameter ~[code Text] }
function TJaddNodeOwner.GetVariableText(const TextName: String;
                                        var Text: String): Boolean;
begin
 Text := '';
 Result := False;                      //by default no variable texts are known
end;

{Reads the content of a file to be included in the documentation unquoted.
~param FileName the name of the file whose content should be inserted unchanged
~param Content  out: the content of the file
~result whether the file was found and its content could be read }
function TJaddNodeOwner.ReadRawFile(const FileName: String;
                                    var Content: String): Boolean;
begin
 Result := False;                      //by default no raw files are read
end;

{Registers a file with additional user documentation to be included in the
 documentation.
~param FileName the name of the file with additional user documentation to be
                read
~result whether the file was found and could be read }
function TJaddNodeOwner.RegisterUserDocumentationFile(const FileName: String):
                                                                       Boolean;
begin
 Result := False;             //by default no additional documentation is read
end;

{Sets the help context for the current comment.
~param HelpContext the help context to be used for the current topic }
procedure TJaddNodeOwner.SetHelpContext(HelpContext: THelpContext);
begin
                                       //by default the help context is ignored
end;

{Tries to inherit documentation for the current position. If possible the
 inherited documentation is added to the specified node.
~param ToNode the node to which the inherited documentation should be added
~result whether documentation could be inherited }
function TJaddNodeOwner.InheritDocumentation(ToNode: TICNCompound): Boolean;
begin
 Result := False;         //by default inheriting documentation does never work
end;

{Changes whether text should be inserted pre-formatted (as-is) in the
 documentation. Nesting of pre-formatted text is allowed.
~param Delta in what direction this flag should be changed,
             either 1 for pre-formatted or -1 for ending pre-formatted text}
procedure TJaddNodeOwner.ChangePreformattedState(Delta: Integer);
begin
 assert((Delta = -1) or (Delta = 1));
 inc(FPreformattedNum, Delta);           //change the flag accordingly
 assert(FPreformattedNum >= 0);
end;

{Returns whether text should be inserted pre-formatted (as-is) in the
 documentation.
~result whether text should be inserted pre-formatted }
function TJaddNodeOwner.GetPreformattedState: Boolean;
begin
 Result := FPreformattedNum > 0;         //in at least one pre-formatted node?
end;

{Returns the index of the parameter with the specified name or -1.
~param ParameterName the name of the parameter
~result the index of the parameter or -1 }
function TJaddNodeOwner.FindParameterIndex(const ParameterName: String):
                                                                       Integer;
begin
 Result := -1;                         //by default no parameters are known
end;

{Sets the index of the parameter whose documentation is currently transformed.
 This is used when inheriting documentation.
~param ParamIndex the index of the parameter }
procedure TJaddNodeOwner.SetCurrentParameterIndex(ParamIndex: Integer);
begin
                                       //by default this information is ignored
end;

{Searches an identifier by its name (possibly with its ~[em path]).
~param Name  the name of the identifier or file (may include its "path")
~param Kind  a hint what kind of identifier or file is searched
~param Links will be filled with the file and identifiers in the path if the
             file or identifier can be found, the last entry will be the
             specified file or identifier; each string will be a part of Name,
             it hat so be concatenated with a dot "." between them to
             regenerate the Name, but case may differ, because the defined
             names of the identifiers will be used instead of that in name; the
             objects to the strings will be either the file or the identifier
             represended by the string }
procedure TJaddNodeOwner.FindIdentifier(const Name: String;
                                        Kind: TFindIdentifierKind; 
                                        Links: TList);
begin
 Assert(Links.Count = 0);
 //by default nothing is found
end;

{Returns the index of the page of user documentation to link to.
~param PageName the name of the page to link to
~result the index of the page to link to, -1 means the main/index page,
        -2 is returned in case the page is unknown }
function TJaddNodeOwner.SearchLinkPage(const PageName: String): Integer;
begin
 Result := -2;                           //no pages are known
end;

{Returns the destination in the help on a GUI to link to.
~param GUILink   the text of the link inside the help on a GUI
~param CommentIndex out: the component/topic to link to inside the help on the
                         form, -1 if the main topic/the form itself, -2 for
                         default comment
~result the index of the form to link to, -1 if link target is unknown }
function TJaddNodeOwner.SearchLinkGUI(const GUILink: String;
                                      var CommentIndex: Integer): Integer;
begin
 Result := -1;                           //help on GUI is not known (supported)
end;

{Returns the value of an option of one of the objects used to generate the
 documentation if it exists.
~param OptionName  the name of the option whose value should be returned
~param OptionValue out: the value of the named option or '' if it does not
                        exist
~returns whether the option exists }
function TJaddNodeOwner.GetOptionValue(const OptionName: String;
                                       var OptionValue: String): Boolean;