ucomments.pas

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

{  JADD - Just Another DelphiDoc: Documentation from Delphi Source Code

Copyright (C) 2003-2008   Gerold Veith

This file is part of JADD - Just Another DelphiDoc.

DelphiDoc is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License version 3 as
published by the Free Software Foundation.

DelphiDoc is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.
}


unit UComments;

{Contains the simple definition of a comment, ~[linkClass TComment], it holds
 the comments of an identifier or file.
}

interface

uses Classes;

type


   { * * *  ***  * * *  ***   TComment   ***  * * *  ***  * * *  }

  //Sections in comments to comment specific parts of the identifiers etc..
  TCommentSection = (
                     //the main comment at the beginning in no special section
                     csComment,
                     //the comment of a (or multiple) parameter(s)
                     csParameter,
                     //the comment of the result of a function
                     csResult,
                     //the comment on an exception, that can be thrown by a
                     //function, procedure, etc.
                     csException,
                     //a link to an identifier, to see also for information
                     csSee,
                     //some text pointing to additional information outside of
                     //the generated documentation
                     csSeeText,
                     //marking the identifier as deprecated, with a comment why
                     csDeprecated,
                     //marking the identifier as not finished, with a
                     //description what's missing
                     csToDo,
                     //marking the identifier as missing some features, that
                     //still have to be implemented, with a description of them
                     csFeature,
                     //gives an example of the usage of the identifier
                     csExample,
                     //names the author of the identifier/file, optionally with
                     //some text describing his changes etc.
                     csAuthor,
                     //gives a version this identifier/file was introduced
                     //or something changed
                     csVersion,
                     //a user definable attribute
                     csAdditionalAttribute1,
                     //a user definable attribute
                     csAdditionalAttribute2,
                     //a user definable attribute
                     csAdditionalAttribute3,
                     //starts a new page (only in the user documentation)
                     csPage,
                     //includes another text file with documentation on the GUI
                     //(only in mode ~[link UMakeDoc.dgkGUIHelp])
                     csGUIInclude,
                     //defines an alias of one (not documented) component to
                     //another (documented) one
                     //(only in mode ~[link UMakeDoc.dgkGUIHelp])
                     csGUIAlias,
                     //adds a manual link to the image
                     //(only in mode ~[link UMakeDoc.dgkGUIHelp])
                     csGUIManual,
                     //documents one or more components on the GUI, i.e. starts
                     //a new topic (only in mode ~[link UMakeDoc.dgkGUIHelp])
                     csGUI);


      //the first section for additional attributes
const csFirstAdditionalAttribute = csAdditionalAttribute1;
      //the last section for additional attributes
      csLastAdditionalAttribute = csAdditionalAttribute3;
      //the number of additional attributes
      AdditionalAttributeCount = Ord(csLastAdditionalAttribute) -
                                 Ord(csFirstAdditionalAttribute);
      //the first section with a name                           
      csFirstNonDefaultComment = Succ(Low(TCommentSection));


type
  //the comments of each section; a list may be nil if it is empty
  TCommentSectionLists = array[TCommentSection] of TStringList;


  {Represents the comments of an identifier or file (or similar). Also used to
   represent the content of a file of user documentations and of help about a
   GUI. }
  TComment = class
  private
    //the comments of each section
    FComments: TCommentSectionLists;

    //names of sections with unknown names
    FOtherNames: TStringList;
    //contents of sections with unknown names
    FOtherComments: TStringList;
  public

    //Creates the object and assigns the comments.
    constructor Create(Comments: TCommentSectionLists;
                       OtherNames, OtherContents: TStrings);
    //Frees the comments and the object.
    destructor Destroy; override;

    //Returns a comment of the section.
    function GetAndDeleteSection(Section: TCommentSection;
                                 var Text: String): Boolean;
    //Clears all comments in a section.
    procedure ClearSection(Section: TCommentSection);
    //Returns a comment of the section with an unknown name.
    function GetAndDeleteOtherSection(const SectionName: String;
                                      var Text: String): Boolean;


    //Returns the names of other sections as a comma separated list.
    function OtherSectionNames: String;
  end;



implementation



   { * * *  ***  * * *  ***   TComment   ***  * * *  ***  * * *  }


{Creates the object and assigns the comments.
~param Comments      the comments to represent
~param OtherNames    names of sections with unknown names; may be nil
~param OtherContents contents of sections with unknown names; may be nil }
constructor TComment.Create(Comments: TCommentSectionLists;
                            OtherNames, OtherContents: TStrings);
var         Section        :TCommentSection;     //counter through all sections
begin
 inherited Create;                               //create the object

 for Section := Low(Section) to High(Section) do //for each section
  //if some comments exist in that section
  if Assigned(Comments[Section]) and (Comments[Section].Count > 0) then
   begin
    FComments[Section] := TStringList.Create;
    FComments[Section].Assign(Comments[Section]);    //copy the comments
   end;


 Assert(Assigned(OtherNames) = Assigned(OtherContents));
 Assert(not Assigned(OtherNames) or (OtherNames.Count = OtherContents.Count));

 //sections with unknown names exist?
 if Assigned(OtherNames) and (OtherNames.Count > 0) then
  begin
   FOtherNames := TStringList.Create;              //create lists
   FOtherComments := TStringList.Create;
   FOtherNames.Assign(OtherNames);                 //copy sections
   FOtherComments.Assign(OtherContents);
  end;
end;

{Frees the comments and the object. }
destructor TComment.Destroy;
var        Section :TCommentSection;             //counter through all sections
begin
 for Section := Low(Section) to High(Section) do //free all comments
  FComments[Section].Free;

 FOtherNames.Free;                               //free unknown sections
 FOtherComments.Free;

 inherited Destroy;                              //free the object
end;


{Gets the content of the first comment in the specified section and removes it.
~param Section the kind of the section to get comment of
~param Text    out: will receive the content of the requested section
~result whether a section of the requested kind was found }
function TComment.GetAndDeleteSection(Section: TCommentSection;
                                      var Text: String): Boolean;
begin
 Result := assigned(FComments[Section]) and (FComments[Section].Count > 0);
 if Result then                            //section exists?
  begin
   Text := FComments[Section][0];           //get the text of the section
   FComments[Section].Delete(0);            //and remove it
  end
 else
  Text := '';                               //return an empty text
end;

{Clears all comments in a section.
~param Section the kind of the section to clear }
procedure TComment.ClearSection(Section: TCommentSection);
begin
 if assigned(FComments[Section]) then     //section not empty?
  FComments[Section].Clear;                 //make it so
end;

{Returns a comment of the section with an unknown name.
~param SectionName the name of the section to get comment of
~param Text        out: will receive the content of the requested section
~result whether an unknown section with the requested name was found }
function TComment.GetAndDeleteOtherSection(const SectionName: String;
                                           var Text: String): Boolean;
var      Index   :Integer;                   //index of the section
begin
 Text := '';                                 //no content so far
 Result := assigned(FOtherNames);            //unknown sections exist?
 if Result then
  begin
   Index := FOtherNames.IndexOf(SectionName);  //search section by the name
   Result := Index <> -1;
   if Result then                              //section found?
    begin
     Text := FOtherComments[Index];              //return its text
     FOtherNames.Delete(Index);                  //and delete the section
     FOtherComments.Delete(Index);
    end;
  end;
end;

{Returns the names of other sections as a comma separated list.
~result the names of other sections }
function TComment.OtherSectionNames: String;
begin
 if assigned(FOtherNames) then               //other sections exist?
  Result := FOtherNames.CommaText              //return their names
 else
  Result := '';                                //no other sections
end;

end.