This package defines headers and comment facilities that help the
developer to document his source code. Using this package, the developer
may add quality in his production.
I did not want to force the user to use rules I would have defined. So I decided to allow user to define his own rules, and even, to map rules with files according to their locations. Rules (templates and parameters) are grouped within a charter.
You can use the default charter as is or customize it to fit your favorite choices.
You can also define a new charter to fit other needs. If you do not define some behaviours, the default ones will be used.
The definition of a charter may require a bit of skill with emacs lisp.
You can see a sample of the result of the use of the package (not very exciting without interactivity...).
This package needs the tempo package which is part of GNU Emacs since version 19.23.
How to design a template?
It is useful to begin a "module" (usually a file) by a commentary header to
describe the content of the module. It contains, at least, a
description of the module (its goal and its functionnalities). It may
also contains the author, the creation date and, the version and the last
update, usually managed by a source control tool.
To be sure that the file is complete (and not truncated), it may be useful to
add a module footer (for instance: "EOF" or "module ends here").
The more helpful feature is the function (procedure, sub-routine, ...) header.
It allows developers to describe the interface of their functions.
This header must contain the description of the following piece of code with
a full description of each parameters. They are classified in three categories:
the inputs, the outputs and those that have the both roles. In the case of
function, the return value must be describe.
The header may also contains the author of the function and the creation date
that may differ from the module ones.
Add a parameter line
The package provides an interactive way to add a parameter line to the header.
Add a parameter line like current one
The package allows to clone a parameter line from the current one.
It is often useful to add in-line comments to separate pieces of code. For instance, table creation and foreign key creation and additional indexes...
People who maintain existing code need to update it to improve, correct or change it.
It is very useful to tag (as reminder) this part of code to track potential
Insert maintenance header
You can insert headers of maintenance block independantly. This allows to
insert a maintenance header at a precise place.
Insert maintenance footer
You can insert footers of maintenance block independantly. This allows to
insert a maintenance footer at a precise place.
Insert full block
You can insert a full (aheader followed by a footer) maintenance block.
It is especially usefull to add a new part of code.
Comment a maintenance region
You can enclose a part of existing code within a maintenance block.
Select the region to tag and call the function.
Tag Removed code
When you remove existing code during a maintenance task, it is welcome to
insert a tag, at the location where the code took place, to inform that
some lines of code have disappeared. Next readers may want to query the source code tool
to retrieve the previous code.
This defines a special header dedicated to log files.
There is several ways to use the package:
- Byte-compile this file and put the compiled file into the scope of your
- Copy prg-comment directory (delivered with the package source)
somewhere on your disk
- Set the variable
with the previous location in your emacs initialization file
(setq prg-comment-material-path "~/.emacs-ext/prg-comment")
- [optional] Design your own charter and put it into the directory
- [optional] Update the lang definitions (located in
<prg-comment-material-path>/lang), if necessary
You can, of course, combine the both call types.
- manual call
- Add the line
to your emacs initialization file (.emacs/_emacs), then select your buffer
and call interactively the function
(autoload 'prg-comment-set-charter "prg-comment")
where <charter> is the name of a defined charter.
prg-comment-set-charter RET <charter> RET
- automatic call
- Add the lines
to your emacs initialization file (.emacs/_emacs), where <major-mode>
is the major mode that want to use prg-comment. Redefine the
(autoload 'prg-comment-use-it "prg-comment")
(add-hook '<major-mode>-hook 'prg-comment-use-it)
'(("~/gnu" . open-source)
("~/work" . my-company)
("~/work/airbus" . airbus)))
prg-comment-charters-alist variable according to each of your
In the previous example, each file edited with the <major-mode> and
located into the
d:/users/atisne/work subtree, will use the my-company
charter; except the files located into the
subtree that will use the airbus charter. The mode will choose the
charter associated to the deeper path declared in the association list
Charters are located in
A charter describes all comment conventions.
The default charter is named
An exhaustive declaration defines:
- the language of the charter
- the maximum column that comments can used
- the column to align field values
- the name of the company you write for
- the character used to build module header
- the character used to build function header
- the character used to build maintenance block
- the character used to build in-line comment
- the template for module header
- the template for module footer
- the template for function header
- the template to begin a maintenance block
- the template to end a maintenance block
- the template for log header
- the number of colums used by in-line comment
- the template for in-line separator
Language string tables are located in
It is a translation table for each field that may be used into templates.
The package will load the table according to the value set into the used
prg-comment-language). The default language
is the one defined into the default charter.
You can change language at any time using the function
How to design a template?
Templates use the tempo technology. Please refer to the tempo documentation.
Additionally, a set of non interactive functions allow you to build your templates. You can also use any of standard emacs lisp functions.
Use this function to retrieve a string from the string table depending on the language used. The input of the function is the key associated to the string and it returns the string in the language currently used. The function returns ?? if the key does not exist.
This function does the same thing as prg-comment-get-text formating the string. It pads with space characters until the limit prg-comment-field-column. Thus, the fields value are aligned.
This set of functions insert a line filled with a special character: a separator line. A character is defined for each type of separator. * may take the values:
The separator for log files is the same as the module one.
|for module separator|
|for function separator|
|for maintenance separator|
|for in-line separator|
- If you can see ?? where you expect a label field, that means
that this field is not known in the language definition currently used.
Please verify, you can find an associative item for this field in the
string table. It must follow the form:
(:FIELD-NAME . FIELD-VALUE)
- If you can see the message The label *XXX* is too long (17). You should decrease its size or increase the parameter *prg-comment-field-column* (15)., that means that the size of the label XXX is greater than the value of the parameter prg-comment-field-column (which defines the column number for fields). You should decrease the size of the label or increase the value of the parameter prg-comment-field-column.
- If you specify a language definition file that does not exist, you
will see the error message The language 'XX' is not supported by the package. Please use one of the following YY,ZZ or define a new language definition file. Please add a language definition file in the directory <material_path>/lang/.
- If you try to set an unknown charter, you will see the error message
The charter definition cannot be found. The file 'XXX' should exists. Please add a charter definition file in the directory <material_path>/charter/.
To skim through the source code.
To download the source code.
To go back to the main page.
Last modified: Sat May 10 17:57:41 +0200 2003