| Example Submission's to CodeCogs |
When you submit source code, there are several main entry fields that CodeCogs requires. These include:
Returns the number of days in the month of a Gregorian calendars.
This function calculates the number of days in a month. The number of days in each month of a year are always the same, except in a leap year, when February gains an extra day. Although we traditionally treat the 29th February as the leap day, a left over remnant of the Roman calendar means that the theoretical leap day occurs on the 24th February - many celebrations occur on this day for this reason. \par References http://www.merlyn.demon.co.uk/leapyear.htm#Feb24
//! {Brief description of function A - typically a copy of description above}
/*!
{Specialisation offered by the function A}
\note {any special restrictions of function A}
\param {details of 1st parameters used}
\param {details of 2nd parameters used}
\param {etc...}
\return {details of any return values}
\Example
\code
{working example}
\b Output:
{output from working example}
\endcode
\author {you}
\todo {further improvement that could be done}
\References:
{any references used}
*/
int functionA(...)
{
...
}
//! {Brief description for function B}
/*!
{Details for function B, as above}
*/
int functionB(...)
CodeCogs use the Doxygen markup standard to incorporate structured documentation with C/C++ source code. The CodeCogs documentation engine generates the html documentation you see for each component by following the lexical logic of C/C++ source code and combining this with the additional documentation supplied in the markup. This approach means all functions, explicitly documented or not, receive a basic level of documentation while allowing users to add/edit further documentation from within their standard development environment.
The CodeCogs documentation wizard creates the documentation (with mark-up) automatically. Users who are familiar with the markup language can enter this directly into the raw documentation that accompanies the code they submit. The rest of this page is dedicated to using Doxygen and how to use it when you are coding:
Like a programming language, the documentation markup has a set of commands and rules which must be followed for the system to correctly document your code.
This documentation should includes a brief and detailed descriptions for each piece of code you submit. If you don't provide a brief or detailed description for a unit of code (i.e. a function, class, etc), then this function will not be shown in the documentation. This can be useful method for hiding uninteresting functions or variables that you don't deem important for the end user. A good example might be private member functions, which an end user should rarely access and as such should be hidden from the documentation. The code you submit should also contain comments targeted to various elements of the code, for instance a parameter list, or description of member variables and functions within a class (see below).
It might sound complex, but if you read through this page and look at the examples we've given at the bottom, you will find that generating great documentation is very easy. Either way, the team at CodeCogs is always available to assist, so if your in any doubt run it by us first! (We also always check documentation before entering it onto the web).
top
The CodeCogs documentation wizard only extracts comment that have an additional explanation mark (!) placed immediately after the start of a line comment or a block comment:
The addition of the explanation mark allows you to add development comments, in the normal style, to your code, which are ignored by the documentation wizard. Traditionally a brief comment comes should come before a detailed comment, and both should occur immediately before the C/C++ function, variable or structure they are detailing, i.e.
//! A function to do something. /*! A function to do something, using the method proposed by Frank and Skinner in their 1993 paper. Returns a double containing something */ // Standard C++ style line comment that remains with the code double toDoSomething(int x) { ... }
Note: The documentation wizard will only incorporate comments of this type for certain C++ elements. These include:
To facilitate the documentation of member variables of a class or struct, you can also use the '!<' command, which informs the wizard that the following comment belongs to the C/C++ element that proceeds the comments, rather than after the comments, i.e.
int a; //!< A single line brief comment on the integer a
Note: C++ elements that are not documented, may be excluded from the documentation. It is therefore particularly important that you document functions and classes.
For consistency, CodeCogs.com suggest that you document all possible C/C++ elements, including those given above. In most cases a brief comment is sufficient, although functions, classes and structs should always have a detailed description.
A more complete example using a range of these Doxygen comments might look like this:
//! A function to do something. /*! A function to do something, using the method proposed by Frank and Skinner in their 1993 paper. Returns a double containing something */ double toDoSomething(int x) { } //! Returns the distance from a point double getDistance() { return m_Distance; } //! A abstract base class defining the base behaviour of rivers class RiverBase { //! The constructor /*! Initialises all the dynamically created stuff*/ RiverBase(); m_numRivers; //!< Number of rivers //! Gets the Number of rivers int getNumRivers(); };