There are two types of RCS headers to use, depending on the relative size of the file. If it is a large file then we use the full RCS header. All source code also must use the full RCS header (*.c, *.h, *.cc, *.cpp, *.java, etc.).
Example 2. Full RCS Header
/************************************************************************
* $Id: developer-guide.en.xml,v 1.7 2004/11/06 00:15:09 elzubeir Exp $
*
* ------------
* Description:
* ------------
* Copyright (c) 2004, Arabeyes, YOUR NAME
*
* HERE ENTER A DESCRIPTION OF THE FILE AND ITS PURPOSE
*
* -----------------
* Revision Details: (Updated by Revision Control System)
* -----------------
* $Date: 2004/11/06 00:15:09 $
* $Author: elzubeir $
* $Revision: 1.7 $
* $Source: /home/arabeyes/cvs/doc/guide/developer/developer-guide.en.xml,v $
*
************************************************************************/
|
However, if it is a small file, like a TODO file or something similar, then we use a small RCS header. Remember that when we say small file, it is not the size in byes only. For example, an obvious file that does not require explanation does not warrant a full RCS header. Use common sense here.
Example 3. Small RCS Header
#--
# filename -- short description (one line)
# $Id: developer-guide.en.xml,v 1.7 2004/11/06 00:15:09 elzubeir Exp $
#--
|
Note that all RCS keywords are enclosed between $ signs. It is automatically expanded once you cvs commit your files.
All source code must be commented. This allows you to generate documentation for your program without having to write extra documentation for the API. The commenting style will depend on the toolset(s) and language(s) used by your project. For example, Java has javadoc which you can use. The same applies to GNOME, KDE and the likes. In the case of not belonging to a group of projects that applies its own source code documentation style, you must default to Doxygen.
Making Doxygen style comments is not hard or complicated. It only requires a negligible learning curve and you should be up and running in less than 5 minutes. The point of this whole exercise is to ensure a certain level of quality of source code. Documenting your code not only allows others to be able to follow your code, it allows you to re-evaluate your logic and helps you in maintaining your code.
You will need to create a Doxyfile which holds the necessary configuration options to generate the documentation. There are also GUI tools that help you in creating this configuration file.
The following is an example from Duali (C++):
Example 4. Doxygen configuration file
#--
# Duali Doxygen Configuration File
# $Id: developer-guide.en.xml,v 1.7 2004/11/06 00:15:09 elzubeir Exp $
#--
PROJECT_NAME = Duali
PROJECT_NUMBER = 0.2
OUTPUT_DIRECTORY = ../doc
OUTPUT_LANGUAGE = English
EXTRACT_ALL = YES
EXTRACT_PRIVATE = YES
EXTRACT_STATIC = YES
EXTRACT_LOCAL_CLASSES = YES
HIDE_UNDOC_MEMBERS = NO
HIDE_UNDOC_CLASSES = NO
HIDE_FRIEND_COMPOUNDS = NO
HIDE_IN_BODY_DOCS = NO
BRIEF_MEMBER_DESC = YES
REPEAT_BRIEF = YES
ALWAYS_DETAILED_SEC = NO
INLINE_INHERITED_MEMB = NO
FULL_PATH_NAMES = NO
STRIP_FROM_PATH =
INTERNAL_DOCS = YES
CASE_SENSE_NAMES = YES
SHORT_NAMES = NO
HIDE_SCOPE_NAMES = NO
VERBATIM_HEADERS = YES
SHOW_INCLUDE_FILES = YES
JAVADOC_AUTOBRIEF = YES
MULTILINE_CPP_IS_BRIEF = NO
DETAILS_AT_TOP = YES
INHERIT_DOCS = YES
INLINE_INFO = YES
SORT_MEMBER_DOCS = YES
DISTRIBUTE_GROUP_DOC = NO
TAB_SIZE = 4
GENERATE_TODOLIST = YES
GENERATE_TESTLIST = YES
GENERATE_BUGLIST = YES
GENERATE_DEPRECATEDLIST= YES
ALIASES =
ENABLED_SECTIONS =
MAX_INITIALIZER_LINES = 30
OPTIMIZE_OUTPUT_FOR_C = NO
OPTIMIZE_OUTPUT_JAVA = NO
SHOW_USED_FILES = YES
#---------------------------------------------------------------------------
# configuration options related to warning and progress messages
#---------------------------------------------------------------------------
QUIET = NO
WARNINGS = YES
WARN_IF_UNDOCUMENTED = YES
WARN_IF_DOC_ERROR = YES
WARN_FORMAT = "$file:$line: $text"
WARN_LOGFILE =
#---------------------------------------------------------------------------
# configuration options related to the input files
#---------------------------------------------------------------------------
INPUT = /home/elzubeir/cvs/arabeyes/projects/duali/src/
FILE_PATTERNS =
RECURSIVE = NO
EXCLUDE =
EXCLUDE_SYMLINKS = NO
EXCLUDE_PATTERNS =
EXAMPLE_PATH =
EXAMPLE_PATTERNS =
EXAMPLE_RECURSIVE = NO
IMAGE_PATH =
INPUT_FILTER =
FILTER_SOURCE_FILES = NO
#---------------------------------------------------------------------------
# configuration options related to source browsing
#---------------------------------------------------------------------------
SOURCE_BROWSER = YES
INLINE_SOURCES = YES
STRIP_CODE_COMMENTS = YES
REFERENCED_BY_RELATION = YES
REFERENCES_RELATION = YES
#---------------------------------------------------------------------------
# configuration options related to the alphabetical class index
#---------------------------------------------------------------------------
ALPHABETICAL_INDEX = NO
COLS_IN_ALPHA_INDEX = 5
IGNORE_PREFIX =
#---------------------------------------------------------------------------
# configuration options related to the HTML output
#---------------------------------------------------------------------------
GENERATE_HTML = YES
HTML_OUTPUT = html
HTML_FILE_EXTENSION = .html
HTML_HEADER =
HTML_FOOTER =
HTML_STYLESHEET =
HTML_ALIGN_MEMBERS = YES
GENERATE_HTMLHELP = NO
CHM_FILE =
HHC_LOCATION =
GENERATE_CHI = NO
BINARY_TOC = NO
TOC_EXPAND = YES
DISABLE_INDEX = NO
ENUM_VALUES_PER_LINE = 4
GENERATE_TREEVIEW = YES
TREEVIEW_WIDTH = 250
#---------------------------------------------------------------------------
# configuration options related to the LaTeX output
#---------------------------------------------------------------------------
GENERATE_LATEX = NO
LATEX_OUTPUT = latex
LATEX_CMD_NAME = latex
MAKEINDEX_CMD_NAME = makeindex
COMPACT_LATEX = NO
PAPER_TYPE = a4wide
EXTRA_PACKAGES =
LATEX_HEADER =
PDF_HYPERLINKS = NO
USE_PDFLATEX = NO
LATEX_BATCHMODE = NO
#---------------------------------------------------------------------------
# configuration options related to the RTF output
#---------------------------------------------------------------------------
GENERATE_RTF = NO
RTF_OUTPUT = rtf
COMPACT_RTF = NO
RTF_HYPERLINKS = NO
RTF_STYLESHEET_FILE =
RTF_EXTENSIONS_FILE =
#---------------------------------------------------------------------------
# configuration options related to the man page output
#---------------------------------------------------------------------------
GENERATE_MAN = NO
MAN_OUTPUT = man
MAN_EXTENSION = .3
MAN_LINKS = NO
#---------------------------------------------------------------------------
# configuration options related to the XML output
#---------------------------------------------------------------------------
GENERATE_XML = NO
XML_SCHEMA =
XML_DTD =
#---------------------------------------------------------------------------
# configuration options for the AutoGen Definitions output
#---------------------------------------------------------------------------
GENERATE_AUTOGEN_DEF = NO
#---------------------------------------------------------------------------
# configuration options related to the Perl module output
#---------------------------------------------------------------------------
GENERATE_PERLMOD = NO
PERLMOD_LATEX = NO
PERLMOD_PRETTY = YES
PERLMOD_MAKEVAR_PREFIX =
#---------------------------------------------------------------------------
# Configuration options related to the preprocessor
#---------------------------------------------------------------------------
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = NO
EXPAND_ONLY_PREDEF = NO
SEARCH_INCLUDES = YES
INCLUDE_PATH =
INCLUDE_FILE_PATTERNS =
PREDEFINED =
EXPAND_AS_DEFINED =
SKIP_FUNCTION_MACROS = YES
#---------------------------------------------------------------------------
# Configuration::addtions related to external references
#---------------------------------------------------------------------------
TAGFILES =
GENERATE_TAGFILE =
ALLEXTERNALS = NO
EXTERNAL_GROUPS = YES
PERL_PATH = /usr/bin/perl
#---------------------------------------------------------------------------
# Configuration options related to the dot tool
#---------------------------------------------------------------------------
CLASS_DIAGRAMS = YES
HIDE_UNDOC_RELATIONS = YES
HAVE_DOT = NO
CLASS_GRAPH = YES
COLLABORATION_GRAPH = YES
TEMPLATE_RELATIONS = YES
INCLUDE_GRAPH = YES
INCLUDED_BY_GRAPH = YES
GRAPHICAL_HIERARCHY = YES
DOT_IMAGE_FORMAT = png
DOT_PATH =
DOTFILE_DIRS =
MAX_DOT_GRAPH_WIDTH = 1024
MAX_DOT_GRAPH_HEIGHT = 1024
GENERATE_LEGEND = YES
DOT_CLEANUP = YES
#---------------------------------------------------------------------------
# Configuration::addtions related to the search engine
#---------------------------------------------------------------------------
SEARCHENGINE = NO
CGI_NAME = search.cgi
CGI_URL =
DOC_URL =
DOC_ABSPATH =
BIN_ABSPATH = /usr/local/bin/
EXT_DOC_PATHS =
|
The above is simply an example and is not meant to be followed rigidly. However, it is expected you do indeed provide proper documentation throughout your code to comply with Doxygen commenting formats. For more information on that, please do consult your friendly Doxygen manual (or look at Duali as a possible example).
It is extremely important that manpages are created for any project. In fact, no releases are to be made without manpages to accompany your program. It is simply unacceptable to not have a manpage for your program. However, you may feel free to also include info(1) pages.
Manpages are relatively simple to make. Here is an example of a manpage:
Example 5. A manpage
.\" Hey, EMACS: -*- nroff -*-
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.TH DUALI 1 "Aug 16, 2003"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh disable hyphenation
.\" .hy enable hyphenation
.\" .ad l left justify
.\" .ad b justify to both left and right margins
.\" .nf disable filling
.\" .fi enable filling
.\" .br insert line break
.\" .sp <n> insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
duali \- The Arabic Spell Checker.
.SH SYNOPSIS
.B duali
.RI \-c\ filename\ [OPTIONS] ...
.SH DESCRIPTION
.PP
.\" TeX users may be more comfortable with the \fB<whatever>\fP and
.\" \fI<whatever>\fP escape sequences to invode bold face and italics,
.\" respectively.
\fBduali\fP is an open source cross-platform Arabic spell checker.
.SH OPTIONS
.TP
.B \-h, \-\-help
Show summary of options.
.TP
.B \-V, \-\-version
Show version of program.
.TP
.B \-c, \-\-check= filename
File to spellcheck (required)
.TP
.B \-C, \-\-charset
Select file character encoding (default utf-8). The options are between utf-8
and cp1256. It is recommended that you only use utf-8.
.TP
.B \-n, \-\-normalize
Switch normalize mode off (default on). The normalize mode strips all diacritic
marks from the spell checked text (recommended).
.TP
.B \-p, \-\-path
Path to dictionary database (this option should probably be set in your
configuration file).
.TP
.B \-v, \-\-verbose
Verbose out (for debugging)
.SH AUTHOR
This manual page was originally written by Mohammed Sameer <uniball (at) gmx dot net>
and later modified and adapted by Mohammed Elzubeir <elzubeir (at) arabeyes dot org>.
|
To learn more about creating manpages, you can always go through the Linux Man Page HOWTO.
No program is ever complete. There is always room for improvement and enhancements. That is why we have TODO lists. Arabeyes projects employ two types of TODO lists: Web-based and text-based. It is the responsibility of the project maintainer to synchronize between the two lists.
The web-based TODO list manager was deployed in order to help project maintainers make it easier for new volunteers to easily find what they can help with. It uses a simple to use web interface and should be rather intuitive.
The text-based TODO's are what you will be placing in CVS. This usually sits in the root of your CVS module. Although it is not mandatory, it is strongly urged that all projects do maintain an up-to-date TODO list.
The format should also be consistent. The format should be as the following example demonstrates:
Example 6. TODO List
#--
# XXX TODO List
# $Id: developer-guide.en.xml,v 1.7 2004/11/06 00:15:09 elzubeir Exp $
#--
+ do x1 and x2 again
+ yet another item.. see, it's very simple
+ do x and do y while maintaining that z remains cool
(*) DONE - Mar. 23, 2001
|
Be sure to keep the "DONE" items at the bottom while the active items on top.
It is always nice to be able to find out what has changed from release to another. If you haven't been updating your ChangeLog as you go along it could be a rather tedious process that you would want to completely put off. However, no release can be made without a ChangeLog file.
With that being said, cvs2cl is to the rescue (http://www.red-bean.com/cvs2cl! Remember how you have been working very hard at making sure your CVS commit logs reflect the work you have been doing? This is one area where it pays off. cvs2cl will generate a ChangeLog based on those CVS commit logs. You can then go through its output and modify it accordingly.
Example 7. ChangeLog
#--
# BiCon Change Log
# $Id: developer-guide.en.xml,v 1.7 2004/11/06 00:15:09 elzubeir Exp $
#--
2004-04-01 08:33 behdad
* README, bin/bicon.in, doc/man/Makefile.am, doc/man/bicon.1,
doc/man/bicon.bin.1: Wow, now bicon(1) works for X terminals too!
2004-04-01 06:44 behdad
* bicon/.cvsignore: One more. Sorry for the noise ;).
2004-04-01 06:44 behdad
* .cvsignore, bconsole/.cvsignore, bjoining/.cvsignore,
font/.cvsignore, keymap/.cvsignore: .cvsignore added for each
directory that needs it. Happy "cvs up"ing :).
2004-04-01 06:43 behdad
* CVSROOT/cvsignore: Added, with typicall autotools based common
files to ignore.
|