Как писать документацию


Идея документации Wacko Wiki Quick Start основана на следующих простых идеях:

  1. В любое время в любом месте кода вы можете сообщить о новшестве всем, кому это может быть интересно.
  2. Документация устроена в форме дерева для облегчения навигации и понимания. Каждый узел имеет свой адрес (возможно, несколько).
  3. Каждый автор должен знать базовую структуру дерева – первые два уровня.

Рассмотрим, как эти идеи реализуются при написании документации.


Начнем с последней. Последняя идея говорит о том, что вы должны знать базовую структуру дерева. Зачем? В основном пользователи ориентируются по ним в попытках найти необходимую информацию.


Рассмотрим первый уровень.

  • Structure – здесь располагаются узлы документации, упорядоченные по структуре.
  • Function – здесь располагаются узлы документации, упорядоченные по функциям.
  • Examples – здесь располагаются узлы документации, отражающие примеры.
  • User – здесь располагается документация для пользователей разного уровня доступа.
  • Version – здесь располагается документация по версиям систем.

Предположим, вы хотите добавить в поставку Quick Start экшн helloworld. Следующая версия QS – 3.1.


<?php
/*!! Structure.Actions.HelloWorld:
Экшн helloworld позволяет поприветствовать текущего пользователя.
  * Параметр:##user## - определяет имя приветствуемого.
@link Structure.Actions, Function.Other, Version.QS.v3s1:
Экшн, позволяющий поприветствовать пользователя.
@link Examples.Other:
Поприветствовать пользователя:
""{{helloworld user="Влад"}}"".
*/
echo "Hello, ".htmlspecialchars($user);
?>


Начнем со строчки:
/*!! Structure.Actions.HelloWorld:


/*!! – необходимо, чтобы следом идущий коммент воспринимался как элемент автодокументации.
Structure.Actions.HelloWorld – указывает базовый адрес данного элемента документации, первое имя. По соглашению, первоначально все элементы сортируются по структуре.
: означает конец списка адресов и начало содержательного текста
Все, что идет ниже данной строчки вплоть до директивы @link – базовый текст этого элемента.


@link Structure.Actions, Function.Other, Version.QS.v3s1:


– означает буквально следующее – сделай данный элемент подразделом указанных разделов, да добавь в них текст, который идет ниже (до следующей директивы @link). Данный элемент введен для реализации идеи 1: когда угодно сообщи о себе всем, кому об этом может быть интересно.


@link Examples.Other:


То же самое.



сокращенная форма записи


<?php
/*!! Structure.Actions.HelloWorld, Function.Other, Version.QS.v3s1:
Экшн, позволяющий поприветствовать пользователя.
*/
?>


это то же самое, что 


<?php
/*!! Structure.Actions.HelloWorld:
Экшн, позволяющий поприветствовать пользователя.
@link Structure.Actions, Function.Other, Version.QS.v3s1:
Экшн, позволяющий поприветствовать пользователя.
*/
?>