mirror of https://github.com/QMCPACK/qmcpack.git
91 lines
2.9 KiB
Plaintext
91 lines
2.9 KiB
Plaintext
/** \page dev_basic Developing QMCPACK
|
|
\section dev_code Code style
|
|
|
|
We have not enforced any coding standard. However, we recommend to adopt "best
|
|
practices" for clean, simple, and logical codes.
|
|
|
|
As the creator of C++ said, there is no coding standard everyone agrees on. Check out Stroustrup's FAQ.
|
|
A few coding standards are emerging. See a sample header file adopted by boost.org
|
|
- indentations: <b>2 space, disable tabs</b>
|
|
- brackets
|
|
\code
|
|
{
|
|
//stuff here
|
|
}
|
|
\endcode
|
|
- loops
|
|
\code
|
|
for (int i=0; i < n; ++i)
|
|
{
|
|
//do the loop
|
|
}
|
|
\endcode
|
|
- class names: choose the name that can mean something to other developers and easy to grep
|
|
- WhatIsThisClass
|
|
- what_is_this_class
|
|
|
|
But, do not use both at the same time, e.g., What_Is_This_Class is like using bold-faced, itallc and color fonts in a document.
|
|
- Local variable names: hide them as much as you can within the current scope, all lower cases preferred.
|
|
- Use <tt>astyle</tt> to format the codes, if your vim or emacs is not set properly.
|
|
\code
|
|
astyle -A1 -s2 -xe file
|
|
\endcode
|
|
|
|
\section dev_doxy How to use doxygen to add a document
|
|
|
|
All the documentation-related materials are in \c qmcpack/docs which has
|
|
- \c doxygen configuration files
|
|
- \c qmcpack.cfg : generate full code documentation
|
|
- \c dev.cfg : generate the master and developers' guide
|
|
- \c ug.cfg : generate userguides
|
|
- subdirectories
|
|
- \c ug : user guide - how to build, input definitions etc
|
|
- \c tutorials : tutorials on specific topics
|
|
- \c dev : developers' guide
|
|
- \c tex : latex files, mostly generated by \c doxygen, some are committed to the
|
|
repository with customization of the image sizes
|
|
|
|
To generate documentations in the output directory on the working system,
|
|
replace the directory names in \c *.cfg files to remove long directory names.
|
|
\code
|
|
STRIP_FROM_PATH = /Users/jnkim/svnwork/qmcpack-trunk/src \
|
|
/Users/jnkim/svnwork/qmcpack-trunk/docs
|
|
\endcode
|
|
and execute
|
|
\code
|
|
make
|
|
\endcode
|
|
|
|
It can take a while to generate user guide, developers' guide, tutorial and
|
|
code documentation in \c doc/output directory. \c output/doxy/index.html is the
|
|
entry point.
|
|
|
|
The developers' and user guide are prepared in *.dox files using
|
|
<a href="http://www.stack.nl/~dimitri/doxygen/manual/markdown.html">Markdown</a>.
|
|
Simply add new files to the INPUT list in \c ug.cfg or \c dev.cfg and run \c doxygen, e.g.
|
|
\code
|
|
INPUT = ug/index.dox ug/gettingstarted.dox ug/somethingnew.dox
|
|
\endcode
|
|
See an example <tt>ug/qmc.dox</tt>.
|
|
|
|
<!--
|
|
Each page has
|
|
\code
|
|
/** \page pagekey What is this for
|
|
|
|
\section seckey Something
|
|
|
|
*/
|
|
\endcode
|
|
-->
|
|
|
|
\c doxygen can generate latex files and \c tex directory has the generated latex files for
|
|
the user guide.
|
|
|
|
These layout files are used to customize the tabs and navigators.
|
|
- \c DoxygenLayout.xml The main layout with \c qmcpack.cfg
|
|
- \c ug_layout.xml for the user guide with \c ug.cfg
|
|
- \c dev_layout.xml for the developers' guide with \c dev.cfg
|
|
- \c tut_layout.xml for the tutorials with \c tut.cfg
|
|
*/
|