LibCGI code formatting and documentation conventions

Code formatting

Documentation conventions

Documenting
Starting
Brief and detailed
Parameters
Grouping

1 - Code formatting

1.1. Use common sense
These are conventions which we try to follow when writing code for LibCGI. They are this way mainly for reasons of taste, however, sticking to a common set of formatting rules also makes it slightly easier to read through our sources. If you want to submit patches, please try to follow these rules.

We know that code formatting is very close to the style of each one of working, but please understand that a code with many diferent styles is hard to work with.

1.2. Hugging braces
Braces in your code should look like one of the following examples:

		for (i = 0; i < 10; i++) {
			[...]
		} 
		else {
			[...]
		}

		for (i = 0; i < 10; i++) 
		{
			[...]
		} 
		else 
		{
			[...]
		}

or even

		for (i = 0; i < 10; i++) {
			[...]
		} else {
			[...]
		}

There is a simple diference for function braces:

	
	int my_function()
	{
		[...]
	}
	
	char *foo()
	{
		[...]
	}

Did you see the {}'s on that?

1.3. Four-space tab indents
Says it all, really.

1.4. Whitespaces
1.4.1.
Conventional operators surrounded by a space character

	a = (b + c) * d;

1.4.2.
C reserved words separated from opening parentheses by a white space

	while (true) {

1.4.3.
Commas followed by a white space

	someFunction(a, b, c);
	int d, e;

1.4.4.
Semicolons followed by a space character, if there is more on line

	for (int a = 0; b++; c < d)

1.5. Switch / Case constructs

	switch (cmd) {
		case option_one:
			bleh();
			break;		
		case option_two:
		case option_three:
			blah();
			break;
		default:
			bloh();
	}

1.6. Naming
1.6.1.
Uppercase chars:

	MY_CONSTANT

1.6.2. Functions and variables All lowercase, which underscore separators

	  
	  int my_function();
	  char **my_another_char_function();

2 - Documentation conventions
We do use Doxygen for generating documentation, which helps a lot. But to get that working well, there are some very easy rules to follow. It is valid to every function of variable that needs to appear in the documentation.

Start commeting using a backslash followed by two asteriscs:

	/**
	* ....
	**/
	int my_function()
	{
		[...]
	}

Brief and detailed comments:

Brief comments are those who appears in the function listing in the documentation. As the name said, is a very short description of the function or variable. It ends when a dot is found. Defailed comments are those who completely describe the function or variable, and may have too many lines as you want. The general idea is to write a good and clear description, which doesn't need to be longer.

	
		/**
		* This is a brief description of the function.
		* 
		* And here is a more detailed description, where
		* you can put some details of the internals of the
		* function.
		**/
		in my_function()
		{
			[...]
		}

Isn't necessary to repeat the brief description in the detailhed section. It is done automatically.

Documenting parameters, return values, author and relacted topics

It is possible to use some special keywords to document parameters and other things;

	@param -> To document parameters
	@return -> Describes the function's return value
	@author -> Puts the author name
	@see -> To include related topics

		/**
		* This is a brief description of the function.
		* 
		* And here is a more detailed description, where
		* you can put some details of the internals of the
		* function.
		*
		* @param *src Source string
		* @param *dst Destiny string, to where the result will be put
		* @author Author Name
		* @return true if all worked fine, 0 if not
		* @see another_function, one_more_function_name
		**/
		int my_another_function(char *src, char *dst)
		{
			[...]
		}

Grouping

To put some kind of functions into a relacted group is easy:

	
		/**
		* @defgroup my_group_name Name of the group
		* @{
		**/

Note that the @defgroup keywork is followed by the internal group name and the "real" name. The the @{ keyword says that this group is starting in this point. To end a group, just put

	
		/**
		* @}
		**/

It works like a code block. Now, every function and variable which a well written commentary block will appear into the group previously defined.

		/**
		* @defgroup libcgi_string String manipulation
		* @{
		**/
		
		/**
		* Explode's documentation here.
		**/
		char *explode()
		{
			[...]
		}
		
		/**
		* str_replace's documentation here.
		**/
		char *str_replace(char *param1, char param2, char param3)
		{
			[...]
		}
		
		/**
		* @}
		**/

Now, let's suppose you have functions you like to be into the same group, but they are into different files. In this case, use "@ingroup" keyword for each function or variable you want to be part of some group:

	/**
	* @ingroup libcgi_string
	**/	
	/**
	* Method's documentation.
	**/
	char *my_another_string_function()
	{
		[...]
	}

Or, if there is many functions into same source file, use the "@addtogroup" keyword instead of @intogroup. In this case you need to close the grouping when you no longer need it, like @defgroup.

	/**
	* @addtogroup libcgi_string
	**/
	/**
	* Documentation
	**/
	char *method_name()
	{
		[..]
	}
	
	/**
	* Documentation
	**/
	void another_function()
	{
		[...]
	}
	
	/**
	* @}
	**/