Home | Products | Downloads | Support | My Account

Step 1   -   Template, configuration and test files

There are several files you can edit to customize visual appearance and output format and text.

You do not need to edit any of them right now, they can be used as is in this tutorial, so if  you wish, you can go
directly to Step 2.

These files are:

• FILEHEADER.TXT This file resides in the root directory, the same directory as the executable.

  The file is a template for text that is inserted on the top of the source code.

  It contains a few variables, for example $DESCRIPTION$. The variables are replaced by real values when the comments are inserted into the PAS file.

  You can remove the file if you don't want this header in your source, you can remover any of the variables if you don't want, it and you can edit the template text as much as you want.

  In any case you may want to change "My Company" to your business' name.

  
  

• RESERVEDWORDS.TXT This file resides in the root directory, the same directory as the executable. The file is used by the application GUI, to syntax highlight Delphi code, and it is used by the Word Automat to syntax highlight Delphi code in the formatted Word document it creates. You will find detailed instructions in the header of this file on how to edit it.

  
  

• DELPHITEMPLATE.DOC This file resides in the root directory, the same directory as the executable.

  This file is used by the Word automat, see the help file for more info. We recommend that you make a backup of this file before you edit it. The file contains several predefined styles that the Word automat is dependent of, you may want to use the default unedited template first to see how it looks before you attempt to edit it.

  
  

• SIMPLECLASS.PASThere are two identical copies of this file, one in the sub directory TestFiles\Input and one in TestFiles\Output. These files are used in this tutorial and they also serve as examples of coding standards that DelphiComments will understand.

  You can read more about coding standards in the help file.

Step 2   -   Scan source files

Start DelphiComments. If you get an error message complaining about MIDAS.DLL not found, see the help file about this! DelphiComments will not run without this file being present in your system.

Figure 1

Select Comments\Scan units from the main menu, a file dialog comes up.

Figure 2

1. Select SIMPLECLASS.PAS This file resides in the subfolder TestFiles\Input.

   You can select multiple files, but this time we select and use only this sample file.

2. Click "Open" in the file dialog.

Figure 3

Files, classes and members found when scanning the file(s) are listed in three datagrids, this way:

1. Scanned files are listed here, in our case just one, simpleclass.pas

2. Classes found in the file selected in the upper datagrid (1) are listed here, in our case there are two classes in simpleclass.pas

3. Properties and methods found in the class selected in the datagrid above (2) are listed here

   The list items in this datagrid will have various colors, prefixes and text decoration dependent of whether they are properties, procedures or functions, and dependent of their visibility.

Step 3   -   Adding and editing comments

DelphiComments has now scanned the Delphi source file you selected, all classes in this file are registered, together with their members. It is now the right time to edit existing comments and/or add new comments.

Figure 4

1. Select the file you want to edit. In our tutorial this is easy, we only have one file

2. Click the "File description" tab

3. Write a suitable description for this file

The file description will replace the $DESCRIPTION$ token in the template text loaded form FILEHEADER.TXT, and it will all together be inserted at the very top of the target source code file.

Text will wrap as usual and linebreaks will be inserted as usual by pressing the Enter key.

Figure 5

1. Select the class you want to edit. In our tutorial we have two classes in one single file

2. Click the "Class" tab

3. Write a suitable description for this class

The class description will be inserted right over the class definition in the target source code, wrapped in <summary></summary> tag pairs.

Text will wrap as usual and linebreaks will be inserted as usual by pressing the Enter key. There are some important notes about linebreaks, see multiple paragraphs below!

Figure 6

1. Click the "Method, parameters and property comments" tab

2. Select the member you want to edit, it is either a property, a procedure or a function.

   You will notice that the panes on the right side will be enabled or disabled dependent of what kind of member you select. For example, when you select a procedure the Returns pane will be disabled since a procedure has no return value. The same with a property, the Parameters pane will be disabled.

3. If a function or procedure has parameters, this pane will be enabled. You can here select each parameter in turn, and add comments. There is no need to describe the format of the comments here, since everything will immediately be visible in the target source after you have let DelphiComments insert the comments in the target source file.

4. For functions, the Returns pane will be enabled. Here you can describe the return value, for example the criteria for when a function returns True or False.

Step 4   -   Inserting comments into the source code

DelphiComments is now ready to insert your new comments into the target source file. There is nothing wrong about using the same file you used when scanning the source, this will most likely be the case in real life. Here in this tutorial we have chosen to use a separate, albeit identical file as the target, to be able to distinguish between the input and output file.

Figure 7

Select Comments\Replace comments from the menu. A Select directory dialog box comes up.

Figure 8

Select the directory in which your target file(s) reside. In our case it is the TestFiles\Output directory. DelphiComments will look for files in this directory that have the same name as those which were initially scanned.

When DelphiComments inserts comments, it first removes all existing comments. Then it will iterate through all files, all classes in those files and through all members and their parameters. If a file, class or a member that was present when scanning is not found in the target file, no error is reported, no exception is thrown. The missing item will just be ignored and DelphiComments will continue and look for the next match.

That is why we select distinct files when scanning, and only a directory when inserting the comments again, no need to specify the file names twice.

Figure 9

This is how comments are inserted into the Delphi source code. There are several ways to do this and some do not clutter the code like this.

However, this has become some sort of a standard, and tools for parsing source code and their comments will understand this format and these tags.

Multiple paragraphs

If you have linebreaks inside the text, so that you get more than one paragraph, each paragraph will be wrapped in <para></para> tag pairs. This is ok when you really want line breaks, for example if you intend to read most of the comments in documents created with documentation tools. Tools like Doc-O-Matic can scan your commented source code, extract comments and will honor these <para></para> tags.

They will however clutter your source code, so if you have no need for linebreaks, just let the text flow and wrap in the editor as you type and do not press the enter key.

That's it!

We wish you luck with DelphiComments, and hope this tutorial was helpful!

DelphiComments has its own forum, and you are always welcome to visit our support pages

We can also recommend subscribing to our newsletters, there is one for DelphiComments too.

The help file contains some more information. A feature not discussed here is saving comments to separate disk files, you do not need to insert them directly into the target source code files. There is more info about this in the help file.

Good luck on commenting Delphi source code using DelphiComments!