Writing Documentation

From wiki.openchemistry.org
Jump to navigation Jump to search

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.
 * @return true if the input file was successfully set, false otherwise.
 */
bool setInputFile(const QString &fileName, const QString &contents);