thodg/libgit2/CONVENTIONS

• Show log

  Commit

• Hash : 0e7fa1fe
  Author :
  Date : 2008-10-31T12:30:04
  

  Note that comments should be doxygen javadoc style Signed-off-by: Shawn O. Pearce <spearce@spearce.org>

Download

• CONVENTIONS

• libgit2 conventions
  ===================
  
  Namespace Prefixes
  ------------------
  
  All types and functions start with 'git_'.
  
  All #define macros start with 'GIT_'.
  
  
  Type Definitions
  ----------------
  
  All types end in '_t'; for example git_oid_t or git_odb_t.
  
  
  Public Exported Function Definitions
  ------------------------------------
  
  All exported functions must be declared as:
  
  ----
  	GIT_EXTERN(result_type) git_modulename_functionname(arg_list);
  ----
  
  
  Semi-Private Exported Functions
  -------------------------------
  
  Functions whose modulename is followed by two underscores,
  for example 'git_odb__read_packed', are semi-private functions.
  They are primarily intended for use within the library itself,
  and may disappear or change their signature in a future release.
  
  
  Calling Conventions
  -------------------
  
  Functions should prefer to return a 'git_result_t' to indicate
  success/failure and supply any output through the first argument
  (or first few arguments if multiple outputs are supplied).
  
  git_result_t status codes are 0 for GIT_SUCCESS and < 0 for an
  error.  This permits common POSIX result testing:
  
  ----
  	if (git_odb_open(&odb, path))
  		abort("odb open failed");
  ----
  
  
  Documentation Fomatting
  -----------------------
  
  All comments should conform to Doxygen "javadoc" style conventions
  for formatting the public API documentation.
  
  
  Public Header Format
  --------------------
  
  All public headers defining types, functions or macros must use
  the following form, where ${filename} is the name of the file,
  after replacing non-identifier characters with '_'.
  
  ----
  	#ifndef INCLUDE_${filename}_h__
  	#define INCLUDE_${filename}_h__
  
  	#include "git_common.h"
  
  	/**
  	 * @file ${filename}.h
  	 * @brief Git some description
  	 * @defgroup ${filename} some description routines
  	 * @ingroup Git
  	 * @{
  	 */
  	GIT_BEGIN_DECL
  
  	... definitions ...
  
  	/** @} */
  	GIT_END_DECL
  	#endif
  ----
  

Download