Writing Documentation: Difference between revisions

From wiki.openchemistry.org
Jump to navigation Jump to search
(Beginnings of documentation of writing documentation ;-))
 
(Added more detail about documentation)
Line 2: Line 2:
<source lang="cpp">
<source lang="cpp">
/**
/**
  * Your documentation goes here.
  * @brief Your documentation goes here.
  */
  */
void doSomething();
void doSomething();
Line 13: Line 13:
* If appropriate, point out alternate/similar classes
* If appropriate, point out alternate/similar classes
* Ideally give some simple examples of using the class
* Ideally give some simple examples of using the class
** Demonstrate core functionality in the simplest way possible
<source lang="cpp">
namespace MoleQueue
{
/*!
* @class JsonRpcClient jsonrpcclient.h <molequeue/client/jsonrpcclient.h>
* @brief The JsonRpcClient class is used by clients to submit calls to an RPC
* server using JSON-RPC 2.0.
* @author Marcus D. Hanwell
*
* Provides a simple Qt C++ API to make JSON-RPC 2.0 calls to an RPC server. To
* create a client connection and call a method the following should be done:
*
@code
#include <molequeue/client/jsonrpcclient.h>


MoleQueue::JsonRpcClient *client = new MoleQueue::JsonRpcClient(this);
client->connectToServer("MyRpcServer");
QJsonObject request(client->emptyRequest());
request["method"] = QLatin1String("listQueues");
client->sendRequest(request);
@endcode
*
* You should connect to the appropriate signals in order to act on results,
* notifications and errors received in response to requests set using the
* client connection.
*/
class JsonRpcClient : public QObject
{
};
} // End namespace MoleQueue
</source>


=Function Descriptions=
=Function Descriptions=


* @brief descriptions:
* @brief descriptions:
**
** Use complete sentences
* Constructors should be more that "Constructor", such as "Constructs the ... with ..."
* Use complete sentences to describe parameters
<source lang="cpp">
/*!
* @brief Set the input file for the job.
* @param fileName The file name as it will appear in the working directory.
* @param contents The contents of the file specified.
*/
void setInputFile(const QString &fileName, const QString &contents);
</source>

Revision as of 12:38, 25 February 2013

We use Doxygen to generate documentation, and make use of the JavaDoc style. They go in the header next to the declaration, all classes should have at a minimum a brief description with one or two sentences explaining what the intended purpose of the class is.

/**
 * @brief Your documentation goes here.
 */
void doSomething();

Class Descriptions

  • Minimum of a brief overview of the class
  • Add include path for users of the class
  • If appropriate, point out alternate/similar classes
  • Ideally give some simple examples of using the class
    • Demonstrate core functionality in the simplest way possible
namespace MoleQueue
{
/*!
 * @class JsonRpcClient jsonrpcclient.h <molequeue/client/jsonrpcclient.h>
 * @brief The JsonRpcClient class is used by clients to submit calls to an RPC
 * server using JSON-RPC 2.0.
 * @author Marcus D. Hanwell
 *
 * Provides a simple Qt C++ API to make JSON-RPC 2.0 calls to an RPC server. To
 * create a client connection and call a method the following should be done:
 *
 @code
 #include <molequeue/client/jsonrpcclient.h>

 MoleQueue::JsonRpcClient *client = new MoleQueue::JsonRpcClient(this);
 client->connectToServer("MyRpcServer");
 QJsonObject request(client->emptyRequest());
 request["method"] = QLatin1String("listQueues");
 client->sendRequest(request);
 @endcode
 *
 * You should connect to the appropriate signals in order to act on results,
 * notifications and errors received in response to requests set using the
 * client connection.
 */

class JsonRpcClient : public QObject
{
};

} // End namespace MoleQueue

Function Descriptions

  • @brief descriptions:
    • Use complete sentences
  • Constructors should be more that "Constructor", such as "Constructs the ... with ..."
  • Use complete sentences to describe parameters
/*!
 * @brief Set the input file for the job.
 * @param fileName The file name as it will appear in the working directory.
 * @param contents The contents of the file specified.
 */
void setInputFile(const QString &fileName, const QString &contents);