You are currently viewing a snapshot of www.mozilla.org taken on April 21, 2008. Most of this content is highly out of date (some pages haven't been updated since the project began in 1998) and exists for historical purposes only. If there are any pages on this archive site that you think should be added back to www.mozilla.org, please file a bug.

Skip to main content

Commenting Mozilla for LXR

When printing directory listings, such as the one for libmime, LXR tries to add to each listing a description of the current directory, each file, and each subdirectory.

Source Code Description

Many Mozilla files have a comment near the beginning of the file describing the file's purpose and function. There are three common formats for such comments.

  1. The comment contains a line beginning with the word "Description:".
    EXAMPLE: 
       /*----------------------------------------------------*/
   /*                                                    */
   /* Name:        <Xfe/Button.h>                        */
   /* Description: XfeButton widget public header file.  */
   /* Author:      Ramiro Estrugo <ramiro@netscape.com>  */
   /*                                                    */
   /*----------------------------------------------------*/
  2. The comment begins with the name of the file followed by a delimiter.
    EXAMPLE: 
       /* mimecont.c --- definition of the MimeContainer class
    */
  3. If neither of these type comments are found then LXR looks for a comment directly after the file's licence header and before any code, including any #define or #include directives.

Descriptions Of Directories

Directory descriptions are found in a README file in that directory, either in a plain text file called README, or in a formatted README.html file. The README file contains both a short and long description. The long description is printed at the top of the directory's file listing as in this listing for rhino. The short description is printed in the parent directory's file listing as in this listing for javascript.

Format Of A Text README File

LXR looks for the short description in a line containing the directory name followed by dashes as a delimiter and a short description. The long description is taken from the rest of the file. If the file is short, the entire file is printed, otherwise, chooses the first few paragraphs until it has used between 10 and 20 lines.

EXAMPLE of a short description: 
  xpfe --- Cross-Platform Front End

Format Of README.html

With html files surround the descriptions with SPAN tags with the proper LXRLONGDESC or LXRSHORTDESC class. This is the long description shown in the rhino directory. 

   <span CLASS=LXRLONGDESC>
   Rhino is an implementation of JavaScript in Java. Documentation can be found
   <a href="http://www.mozilla.org/js/rhino/rhino.html">here</a>.
   <span>

Here is the short description of rhino shown in the javascript directory, rhino's parent.

   <span CLASS=LXRSHORTDESC>
   Rhino: JavaScript in Java<p>
   </span>