这篇简短的文章会帮助你更好地了解我们的文档过程和适当的指导方针和格式提交你的文档。

通常有三个主要类型的文档,您可以提交:

  • 开发/测试/用户文档

    • 如何设置一个构建环境

    • 如何设置一个QEMU测试环境

    • 如何设置一个VMware测试环境

  • API文档

  • 建筑和公用文档

    • 内核NT / ReactOS的体系结构

    • 安全子系统,Win32 NT / ReactOS的体系结构

    • 帮助文件的应用程序,如记事本,钙

    • 参考指南cmd等应用程序

    • 通用操作系统帮助文件(用于帮助和支持)

开发/测试/用户文档

这种类型的文档,简单地使用Wiki和添加自己的在适当的页面提示/脚本/帮助。 他们中许多人正在建设,WaxDragon一定会感谢你的帮助!

API文档

这意味着文档API函数,类似一个你会发现在MSDN,OSR,等等。这应该直接在源代码中,当前doxygen-recognizable格式,我们使用:

 /*++
  * @name CsrApiRequestThread
  *
  * The CsrApiRequestThread routine handles incoming messages or connection
  * requests on the CSR API LPC Port.
  *
  * @param Parameter
  *        System-default user-defined parameter. Unused.
  *
  * @return The thread exit code, if the thread is terminated.
  *
  * @remarks Before listening on the port, the routine will first attempt
  *          to connect to the user subsystem.
  *
  *--*/
 NTSTATUS
 NTAPI
 CsrApiRequestThread(IN PVOID Parameter)
 {
 … }

注 意,有很多种类似的标题中使用源代码。 这些都是错误的,只是反映了缺乏标准化的头。 如果你喜欢一个有用的清洁任务,创建适当的标题为每个公共功能模块将很有帮助。 最终,所有公共和私有函数ReactOS模块应该有一个标题。 从那里,Doxygen可以创建文档,所以你不需要担心任何额外的格式。

建筑和公用文档

到 目前为止最长和最艰巨的类型,也可能是最有用的。 这些文档的例子包括DPC队列的内部,LSA算法,NT cmd命令。 exe支持。 尽管架构文档存在于书如在Windows 2000,Windows NT内部,Win32程序员的食谱,等等。(和一些根本不存在的),没有一个是免费自由文档许可协议如GNU FDL和知识共享。 应用,如钙、记事本等,还需要相关信息。 hlp或。 chm帮助文件,这样用户可以读到他们(我们不能仅仅复制/粘贴专有.hlp /。 chm文件)

提交类型如下:

  • 架构文档:一个高质量的校对技术文件清楚地解释你正在讨论技术话题。 最好是在。 pdf格式或odf。 医生,只要它不包含任何特性也使它通过OpenOffice.org或Abiword不可读。 你应该把这ros-dev邮件列表进行审查。

  • 应 用程序文档,包括命令行参考指南和操作系统帮助和支持:编译。 hlp和。 chm文件以类似的方式设计和结构化的官方文档(用户将熟悉这样)。 你不能简单地复制/粘贴,称之为自己的官方文档。 为两个。 hlp和。 化学加工,确保你还有原来的源文件(如HTML)。 请发布那些ros-dev邮件列表进行审查。 如果你没有一个.hlp /。 chm编译器,我们可以为你做这些,但我们会很感激如果你确保他们会出现在观众的帮助。 (有几个指南在网上如何创建良好的帮助文件,并使用Windows的指导)。






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

Contents

1 Types of documentation

2 Developer/tester/user documentation

3 API Documentation

4 Architectural and Utility 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:

/*++
 * @name CsrApiRequestThread
 *
 * The CsrApiRequestThread routine handles incoming messages or connection
 * requests on the CSR API LPC Port.
 *
 * @param Parameter
 *        System-default user-defined parameter. Unused.
 *
 * @return The thread exit code, if the thread is terminated.
 *
 * @remarks Before listening on the port, the routine will first attempt
 *          to connect to the user subsystem.
 *
 *--*/
NTSTATUS
NTAPI
CsrApiRequestThread(IN PVOID Parameter)
{
… }

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).