ROS Documentation Guide

Материал из Русский WINE
Перейти к: навигация, поиск

Работа с документацией

Эта короткая статься поможет вам лучше понять процесс создания, редактирования и форматирования технической документации, используемой в деятельности проекта.

Типы документации

Существует три типа документации, с которыми вам придётся иметь дело:

  • Документация разработчика/тестера/пользователя
    • Установка среды сборки
    • Установка среды тестирования на основе 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).
ReactOS
Search.png
Доклады
О ReactOSARWINSSЧастовстречаемые заблуждения о ReactOS
Информация Новости Выпуски новостейПереводы блоговНовости проектаВидео про ReactOSReactOS на ХабреUSB от Вадима Галянта
Разработка Руководство по программированиюОтсутствующая функциональностьВетви разработкиКомпоненты системыReactOS и WineПлан работРазработчикиСовместимость с dll WindowsНаиболее значимые изменения за годИспользуемые проектыGoogle Summer of CodeИзвестные проблемы
Порты AMD64ARMXboxPowerPC
Компоненты Файловые системыРежим совместимостиОтчеты об ошибкахПечатьUSBЯдро
Загрузчик Восстановление MBRЗагрузка из GRUBПараметры загрузки
Прочее ARWINSSПриложения в ReactOSОформление ReactOS
Другое КоординаторыТипы ядерFreeWin95"Пасхальные яйца" в ReactOS
Помощь
RAM-диск ReactOS по PXEс жесткого диска
Разработка Стиль написания кодаСтандарты RC-файловРабота с документациейВенгерская нотацияGNU Indent • [ Subversion : ветвислияниеиспользование TortoiseSVN ] • Основы переводаОтправка патчей
Репорты Отладка в VirtualBoxОтладка на экранДобавление программы в менеджер приложенийОтправка отчетов
Отладка Com0comGDBKdbgRossym.gdbRoswin.gdbWinDBGРуководство по WinDBGВключение трассировки ядраКоды DPRINTУдалённый отладчик ReactOS
Сборка CMakeRBuildФайлы RBuildАвтоматическое копирование файловСборка MINGW-w64Сборка модулейСреда сборки
Тестирование VirtualBoxVMwareQEMUHyper-VНеобходимый объём дискаПеренос файлов на виртуальный дискУстановка ReactOSУстановка драйверов
Сеть Общие папкиSambaNFS
Игры Установка DirectPlay
Обновление ReactOSЗагрузочная флешкаЧем можно помочь проектуСоздание нового пользователяЗвук и сеть в VirtualBoxСъемка и публикация видеоIRC-каналСторонние компоненты
Обзоры ОболочкаNTVDMWOWCommunity Edition