Difference between revisions of "Writing Documentation"

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 11: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);