prg-comment documentation


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
Material description
How to design a template?

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


  1. Byte-compile this file and put the compiled file into the scope of your load-path
  2. Copy prg-comment directory (delivered with the package source) somewhere on your disk
  3. 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")
  4. [optional] Design your own charter and put it into the directory <prg-comment-material-path>/charters
  5. [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


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:


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.


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:
modfor module separator
fctfor function separator
maintfor maintenance separator
in-linefor in-line separator
The separator for log files is the same as the module one.


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