Difference between revisions of "Documentation Guidelines"

From ReactOS Wiki
Jump to: navigation, search
(There was a Wrong doxygen comment.)
(API Documentation: update from Coding Style)
 
Line 22: Line 22:
  
 
== API Documentation ==
 
== API Documentation ==
 
+
This means documentation for API functions, similar as to the one you would find on MSDN, OSR, etc. This should go directly in the source code, following the current [https://doxygen.reactos.org/ doxygen-recognizable] format that we use:
This means documentation for API functions, similar as to the one you would find on MSDN, OSR, etc. This should go directly in the source code, following the current doxygen-recognizable format that we use:
 
 
<syntaxhighlight lang="c">
 
<syntaxhighlight lang="c">
/**
+
/**
  * @name CsrApiRequestThread
+
* @brief Do nothing for 500ms.
  * @implemented
+
*
  *
+
* (optional) Description of what the function does. This part may refer to the parameters
  * The CsrApiRequestThread routine handles incoming messages or connection
+
* of the function, like @p param1 or @p param2. A word of code can also be
  * requests on the CSR API LPC Port.
+
* inserted like @c this which is equivalent to <tt>this</tt> and can be useful
  *
+
* to say that the function returns a @c void or an @c int. If you want to have
  * @param Parameter
+
* more than one word in typewriter font, then just use @<tt@>.
  *       System-default user-defined parameter. Unused.
+
* Note the empty line before brief, it's important for splitting brief and detailed descriptions.
  *
+
*
  * @return The thread exit code, if the thread is terminated.
+
* @param[in] InputParameter
  *
+
* Description of the parameter.
  * @remarks Before listening on the port, the routine will first attempt
+
*
  *         to connect to the user subsystem.
+
* @param[out] OutputParameter
  *
+
* Description of the parameter.
  **/
+
*
  NTSTATUS
+
* @param[in,out] InputOutputParameter
  NTAPI
+
* Description of the parameter.
  CsrApiRequestThread(IN PVOID Parameter)
+
*
  {
+
* @param SomeParameter
 
+
* Bleh, bleh :)
  }
+
*
 +
* @return
 +
* STATUS_SUCCESS in case of success, STATUS_UNSUCCESSFUL
 +
* otherwise.
 +
  *
 +
  * @see SomeOtherAPI
 +
  *
 +
  * @remarks Must be called at IRQL == DISPATCH_LEVEL
 +
  *
 +
  */
 +
NTSTATUS
 +
SomeAPI(UINT32 InputParameter, UINT32 *OutputParameter, UINT32 *InputOutputParameter);
 
</syntaxhighlight>
 
</syntaxhighlight>
 +
Consider looking into [http://www.doxygen.nl/manual/commands.html Doxygen manual] for the full list of the commands.
 +
 +
For tagging a function as not implemented, use <code>@unimplemented</code> statement before <code>@brief</code>.
 +
 
Note that there are many kinds of similar headers used throughout the source code. These are WRONG and simply reflect the lack of a standardized header. If you'd like a helpful janitorial task, creating proper headers for every public function in the module would be very helpful. Eventually, all public and private functions in ReactOS modules should have a header like that. From there, Doxygen can create the documentation, so you don't have to worry about any additional formatting.
 
Note that there are many kinds of similar headers used throughout the source code. These are WRONG and simply reflect the lack of a standardized header. If you'd like a helpful janitorial task, creating proper headers for every public function in the module would be very helpful. Eventually, all public and private functions in ReactOS modules should have a header like that. From there, Doxygen can create the documentation, so you don't have to worry about any additional formatting.
  

Latest revision as of 12:44, 9 July 2019

This short article will help you better understand our documentation process and the proper guidelines and format for submitting your documentation.

Types of documentation

There are generally three main types of documentation that you can submit:

  • Developer/tester/user documentation
    • How to setup a build environment
    • How to setup a QEMU testing environment
    • How to setup a VMware testing environment
  • API Documentation
  • Architectural and Utility Documentation
    • Kernel Architecture of NT/ReactOS
    • Security, Subsystem, Win32 Architecture of NT/ReactOS
    • Help files for applications such as notepad, calc
    • Reference guides for applications such as cmd
    • Generic OS help files (for Help & Support)

Developer/tester/user documentation

For this kind of documentation, feel free to simply use the Wiki and add your own tips/scripts/help on the appropriate pages. Many of them are currently under construction, and WaxDragon would surely appreciate your help!

API Documentation

This means documentation for API functions, similar as to the one you would find on MSDN, OSR, etc. This should go directly in the source code, following the current doxygen-recognizable format that we use:

/**
 * @brief Do nothing for 500ms.
 *
 * (optional) Description of what the function does. This part may refer to the parameters
 * of the function, like @p param1 or @p param2. A word of code can also be
 * inserted like @c this which is equivalent to <tt>this</tt> and can be useful
 * to say that the function returns a @c void or an @c int. If you want to have
 * more than one word in typewriter font, then just use @<tt@>.
 * Note the empty line before brief, it's important for splitting brief and detailed descriptions.
 *
 * @param[in] InputParameter
 * Description of the parameter.
 *
 * @param[out] OutputParameter
 * Description of the parameter.
 *
 * @param[in,out] InputOutputParameter
 * Description of the parameter.
 *
 * @param SomeParameter
 * Bleh, bleh :)
 *
 * @return
 * STATUS_SUCCESS in case of success, STATUS_UNSUCCESSFUL
 * otherwise.
 *
 * @see SomeOtherAPI
 *
 * @remarks Must be called at IRQL == DISPATCH_LEVEL
 *
 */
NTSTATUS
SomeAPI(UINT32 InputParameter, UINT32 *OutputParameter, UINT32 *InputOutputParameter);

Consider looking into Doxygen manual for the full list of the commands.

For tagging a function as not implemented, use @unimplemented statement before @brief.

Note that there are many kinds of similar headers used throughout the source code. These are WRONG and simply reflect the lack of a standardized header. If you'd like a helpful janitorial task, creating proper headers for every public function in the module would be very helpful. Eventually, all public and private functions in ReactOS modules should have a header like that. From there, Doxygen can create the documentation, so you don't have to worry about any additional formatting.

Architectural and Utility Documentation

By far the lengthiest and most arduous type, it's also possibly the most useful. Examples of such documentation include the internals of DPC Queuing, the LSA algorithms, and the commands that the NT cmd.exe supports. Although architectural documentation exists in books such as Inside Windows 2000, Windows NT Internals, Win32 Programmer's Cookbook, etc. (and some doesn't exist at all), none of it is freely available under a Free documentation license such as the GNU FDL or Creative Commons. Applications such as calc, notepad, and others, also need relevant information in a .hlp or .chm help file, so that users can read about them (we can't just copy/paste the proprietary .hlp/.chm files)

The submission types are as follows:

  • For architectural documents: a high-quality proof-read technical document clearly explaining the technical topic that you are discussing. Preferably in .pdf format or OpenDocument, or .doc as long as it doesn't contain any features which would make it unreadable by OpenOffice.org or Abiword. You should post this to the ros-dev mailing list for review.
  • For application documentation, including command-line reference guides and OS Help & Support: a compiled .hlp and .chm file designed and structured in a similar way to the official documentation (so that users will be familiar with it). You must NOT simply copy/paste the official documentation and call it your own. For both .hlp and .chm, make sure that you still have the original source files (e.g. HTML) as well. Please post those to the ros-dev mailing list for review. If you do not have a .hlp/.chm compiler, we can do it for you, but we would appreciate it if you made sure that they will show up fine in the help viewer. (There are several guides online on how to create good help files, and use the Windows ones for guidance).