Merge pull request #43 from adamreeve/style_guide

Documentation update

doc/doxygen/additional_doc/code_style.dox

@@ -134,6 +134,21 @@
 
 - Pre-processing for file inclusion and conditional compilation are allowed. 
 
+\section commit_messages Commit messages
+
+- Commit messages must describe what a change does, and preferably also why the change was made if that is not obvious.
+- The recommended format for a commit message is to have the first line as a short summary, including the tracker number that the commit relates to. Then there should be a blank line and any further description of the change which can be in paragraphs or bulleted.
+- If there is no relevant tracker item then this should be stated.
+
+\subsection example_commit_message Example commit message
+
+\verbatim
+1234: Add a new finite elasticity constitutive relation
+
+Description of what the constitutive relation is used for
+and a reference to the paper it is described in.
+\endverbatim
+
 \section sample_module Sample module
 
 \verbatim

doc/doxygen/additional_doc/local-examples.dox

@@ -1,23 +1,23 @@
 /*!
 \page local-examples Examples
 
-\section example_how How to add an example \subsection example_code Code Level
-- Use svn copy to copy an existing example folder to the same directory.
+\section example_how How to add an example
+
+\subsection example_code Create example code
+- Copy an existing example folder to the same directory.
 - Rename the name of the folder
-- Rename the fortran file in src folder
-- Rename the Visual Studio configuration files and change the configurations inside.
-- Note that the examples are able to be nested. In order to do this, in linux, you need to add an EXAMPLE_PATH in the Makefile e.g., EXAMPLE_PATH=Bioelectrics/ for the Monodomain example.
+- Rename the Fortran file in src folder
+- Note that the examples are able to be nested. In order to do this, in Linux, you need to add an EXAMPLE_PATH in the Makefile e.g., EXAMPLE_PATH=Bioelectrics/ for the Monodomain example.
   For the Visual Studio files it is best to edit the Fortran.vfproj files to ensure the library paths and object paths are correct.
 - Change the source code for the new example
 
-\subsection example_document Document Level
-- Add entry into the example source file using example tag and including the path from examples directory. 
-- Modify the file cm/examples/examplesLogger.py, add the relative logger entry with the example path from examples folder as argument. For example, \code logExample(path="ClassicalField/AnalyticLaplace") \endcode
-- Add entry into the example source file using htmlinclude tag to include the file generated by examplesLogger.py, e.g. \code \htmlinclude ClassicalField/AnalyticLaplace/history.html \endcode 
+\subsection example_document Documenting the example
+- Add a Doxygen entry into the example source file using an example tag and including the path from examples directory.
+- Add an entry into the example source file using an htmlinclude tag to include the file generated when testing the example, e.g. \code \htmlinclude ClassicalField/AnalyticLaplace/history.html \endcode
 
-\subsection example_build Build Level
+\subsection example_build Automated testing
 If you want to add an example into the nightly builds in the buildbot system:
-- Add a file named "nightlytest.prop" under the example directory. 
+- Add a file named "nightlytest.prop" under the example directory.
 - There are three types of property ids.
    - 42TestingPointsPATH: the root directory of 42TestingPoints from the project's examples directory. If the example is executed in the same directory as the file, we don't need to specify this.
    - TestingPATH.x: x is the index starting from 0. This is used to substitute the common part of the path from 42TestingPointsPATH for each test point. It will be referenced in the TestingPoint.x
@@ -26,6 +26,6 @@ If you want to add an example into the nightly builds in the buildbot system:
       - arguments: the command line arguments during the execution
       - expected output directory (optional): directory contains expected outputs from executing path
       - output directory (optional): directory contains outputs from executing path.
-- If you don't want the example(s) to be run nightly, but weekly, just name the file "weeklytest.prop" instead. 
+- If you don't want the example(s) to be run nightly, but weekly, just name the file "weeklytest.prop" instead.
 - For example of the configuration, please refer to <OPENCMISS_ROOT>/cm/examples/FluidMechanics/42Master/weeklytest.prop or <OPENCMISS_ROOT>/cm/examples/ClassicalField/Laplace/Laplace/nightlytest.prop
 */

doc/doxygen/additional_doc/object_interfaces.dox

@@ -6,29 +6,29 @@
 - Should be extensible so that extra parameters can be added at a later stage without causing problems
 \section rules General Rules
 - Objects identified by a unique user number
-- Objects are initialised with a OBJECT_INITIALISE call
-- Objects are finalised with a OBJECT_FINALISE call
-- Objects are created with a pair of OBJECT_CREATE_START and OBJECT_CREATE_FINISH calls
-- Objects are destroyed with a OBJECT_DESTROY call
-- Object parameters are set with a number of OBJECT_PARAMETER_SET calls between the START and FINISH calls
-- START call initialises OBJECT and sets default parameters. SET calls modify default parameters. FINISH call finalises the object
+- Objects are initialised with a CMISSObjectTypeInitialise call
+- Objects are finalised with a CMISSObjectTypeFinalise call
+- Objects are created with a pair of CMISSObjectCreateStart and CMISSObjectCreateFinish calls
+- Objects are destroyed with a CMISSObjectDestroy call
+- Object parameters are set with a number of CMISSObjectParameterSet calls between the CreateStart and CreateFinish calls
+- CreateStart call initialises Object and sets default parameters. Set calls modify default parameters. CreateFinish call finalises the object
 \section example Example(Basis functions)
 \code
 !Initialise the basis functions.
-CALL BASES_INITIALISE(ERR,ERROR,*999)
-!Start the creation of a basis with a user number of 1. 
+CALL CMISSBasesTypeInitialise(Basis,Err)
+!Start the creation of a basis with a user number of 1.
 !The default is tri-linear Lagrange
-CALL BASIS_CREATE_START(1,BASIS,ERR,ERROR,*999)
+CALL CMISSBasisCreateStart(1,Basis,Err)
 !Set the number of xi directions to 2.
-CALL BASIS_NUMBER_OF_XI_SET(BASIS,2,ERR,ERROR,*999)
+CALL CMISSBasisNumberOfXiSet(Basis,2,Err)
 !Set the interpolation to be cubic Hermite*quadratic Lagrange.
-CALL BASIS_INTERPOLATION_XI_SET(BASIS,(/CUBIC_HERMITE,QUADRATIC_LAGRANGE/),ERR,ERROR,*999)
+CALL CMISSBasisInterpolationXiSet(Basis,[CMISSBasisCubicHermiteInterpolation,CMISSBasisQuadraticLagrangeInterpolation],Err)
 !Finish the creation of the basis.
-CALL BASIS_CREATE_FINISH(BASIS,ERR,ERROR,*999)
+CALL CMISSBasisCreateFinish(Basis,Err)
 !Destroy the basis with the user number 1.
-CALL BASIS_DESTROY(1,ERR,ERROR,*999)
+CALL CMISSBasisDestroy(1,Err)
 !Finalise the basis functions.
-CALL BASES_FINALISE(ERR,ERROR,*999) 
+CALL CMISSBasisTypeFinalise(Basis,Err)
 \endcode
 
-*/
+*/