ROS Documentation Guide
Содержание
Работа с документацией
Эта короткая статься поможет вам лучше понять процесс создания, редактирования и форматирования технической документации, используемой в деятельности проекта.
Типы документации
Существует три типа документации, с которыми вам придётся иметь дело:
- Документация разработчика/тестера/пользователя
- Установка среды сборки
- Установка среды тестирования на основе QEMU
- Установка среды тестирования на основе VMware
- Документация по API
- Документация по архитектуре и утилитам
- Архитектура ядра NT/ReactOS
- Безопасность, подсистемы, архитектура Win32 NT/ReactOS
- Файлы справки для таких приложений, как, например notepad и calc
- Справочники команд, используемых, например в cmd
- Общие файлы справки ОС (Справка и поддержка)
Документация разработчика/тестера/пользователя
Для создания и редактирования этого типа документации воспользуйтесь официальной Wiki RoS, куда вы можете добавить свои подсказки и скрипты на соответствующие страницы. Так же дополняйте и нашу неофициальную вики , мы будем вам очень благодарны за это!
Документация по API
Этот тип документации подразумевает под собой документацию по функциям API, аналогичную той, что вы можете найти в MSDN, OSR и т.п. Для этого придётся обратиться непосредственно к исходному коду и воспользоваться форматом, который будет понятен используемому нами Doxygen:
/*++ * @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 (DPC Queue), алгоритмам LSA, и комаднам, поддерживаемым cmd.exe в NT. Хотя большое количество документации по архитектуре и содержится таких книгах, как Inside Windows 2000, Windows NT Internals, Win32 Programmer's Cookbook и прочих (хотя достаточно много чего в них опущено), ни одна из них не доступна на условиях свободных лицензий, например GNU FDL или Creative Commons. Таким приложениям, как calc, notepad и прочим также требуется описание и прочая информация о них в файле справки в формате .hlp или .chm, что позволит пользователям ознакомиться со сведениями о них (не забывайте, мы не можем просто скопировать проприетарные файлы .hlp/.chm или их содержимое).
Документация должна быть приведена к следующему виду:
- Документация по архитектуре: очень качественно вычитанный и проверенный документ, дающий ясное представление о сути технической статьи, о которой пойдёт речь. Предпочтительными форматами являются формат .pdf, OpenDocument, или даже .doc, но лишь при том условии, если он может быть корректно прочитан OpenOffice.org или Abiword. Для дальнейшего рассмотрения документа, вам необходимо опубликовать его в списке рассылки ros-dev.
- Документация для приложений, включая справочники по командам командной строки и файлы справки и поддержки самой ОС: Скомпилированные файлы в формате .hlp и .chm, созданные и структурированные таким же образом, как и официальная документация (пользователям будет проще в ней разобраться). Вы НЕ можете просто скопировать информацию из официальной документации и выдать её за свою. Что касается файлов .hlp и .chm, убедитесь, что у вас остались оригинальные исходные файлы (т.е. HTML). Затем, опубликуйте результаты своей работы в списке рассылки ros-dev для дальнейшего их рассмотрения. Если у вас нет компилятора .hlp/.chm, то мы можем скомпилировать исходные файлы за вас, однако мы будем очень признательны, если вы убедитесь, что они правильно выглядят и функционируют в программе просмотра справки. (В Сети существует несколько инструкций по созданию файлов справки, а в качестве примера правильного оформления справки можно взглянуть на файлы справки из Windows).
