|
prg-comment documentation
|
Abstract
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.
Package's features
Usage
Material description
How to design a template?
Troubleshooting
Download
Package's features
Module header
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.
interactive function
insert-mod-header
Module footer
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").
interactive function
insert-mod-footer
Function header
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.
interactive function
insert-fct-header
Add a parameter line
The package provides an interactive way to add a parameter line to the header.
interactive function
insert-new-param
Add a parameter line like current one
The package allows to clone a parameter line from the current one.
interactive function
insert-new-param-like-current
In-line comment
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...
interactive function
insert-in-line
Maintenance block
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
side effects.
Insert maintenance header
You can insert headers of maintenance block independantly. This allows to
insert a maintenance header at a precise place.
interactive function
insert-maint-header
Insert maintenance footer
You can insert footers of maintenance block independantly. This allows to
insert a maintenance footer at a precise place.
interactive function
insert-maint-footer
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.
interactive function
insert-maint
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.
interactive function
comment-maint-region
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.
interactive function
insert-removed-code
Log header
This defines a special header dedicated to log files.
interactive function
insert-log-header
Usage
- Byte-compile this file and put the compiled file into the scope of your
load-path
- Copy prg-comment directory (delivered with the package source)
somewhere on your disk
- Set the variable
prg-comment-material-path
with the previous location in your emacs initialization file
(.emacs/_emacs)
(setq prg-comment-material-path "~/.emacs-ext/prg-comment")
- [optional] Design your own charter and put it into the directory
<prg-comment-material-path>/charters
- [optional] Update the lang definitions (located in
<prg-comment-material-path>/lang), if necessary
There is several ways to use the package:
- manual call
- Add the line
(autoload 'prg-comment-set-charter "prg-comment")
to your emacs initialization file (.emacs/_emacs), then select your buffer
and call interactively the function
prg-comment-set-charter RET <charter> RET
where <charter> is the name of a defined charter.
- automatic call
- Add the lines
(autoload 'prg-comment-use-it "prg-comment")
(add-hook '<major-mode>-hook 'prg-comment-use-it)
(setq prg-comment-charters-alist
'(("~/gnu" . open-source)
("~/work" . my-company)
("~/work/airbus" . airbus)))
to your emacs initialization file (.emacs/_emacs), where <major-mode>
is the major mode that want to use prg-comment. Redefine the
prg-comment-charters-alist variable according to each of your
personal workspaces.
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 d:/users/atisne/work/airbus
subtree that will use the airbus charter. The mode will choose the
charter associated to the deeper path declared in the association list
prg-comment-charters-alist.
You can, of course, combine the both call types.
Material description
Charter
Charters are located in <prg-comment-material-path>/charters.
A charter describes all comment conventions.
The default charter is named default.el.
An exhaustive declaration defines:
- the language of the charter
prg-comment-language
- the maximum column that comments can used
prg-comment-max-column
- the column to align field values
prg-comment-field-column
- the name of the company you write for
prg-comment-company
- the character used to build module header
prg-comment-mod-char
- the character used to build function header
prg-comment-fct-char
- the character used to build maintenance block
prg-comment-maint-char
- the character used to build in-line comment
prg-comment-in-line-char
- the template for module header
prg-comment-mod-header
- the template for module footer
prg-comment-mod-footer
- the template for function header
prg-comment-fct-header
- the template to begin a maintenance block
prg-comment-maint-header
- the template to end a maintenance block
prg-comment-maint-footer
- the template for log header
prg-comment-log-header
- the number of colums used by in-line comment
prg-comment-in-line-width
- the template for in-line separator
prg-comment-in-line-sep
Language
Language string tables are located in <prg-comment-material-path>/lang.
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
charter (prg-comment-language). The default language
is the one defined into the default charter.
You can change language at any time using the function prg-comment-set-language.
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.
prg-comment-get-text
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.
prg-comment-pad-field
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.
prg-comment-*-sep
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:
mod | for module separator |
fct | for function separator |
maint | for maintenance separator |
in-line | for in-line separator |
The separator for log files is the same as the module one.
Troubleshooting
- 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.
Aurélien TISNÉ
Last modified: Sat May 10 17:57:41 +0200 2003