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

Во первых документ должен иметь тип - то есть то, что документ описывает, а конкретно это может быть класс, интерфейс, функция, плагин, тема, инструкции, и возможно еще что то, о чем я пока не знаю, а узнаю только тогда, когда начну писать документацию. У класса имеются свойства: родительский класс, дочерние классы, интерфейсы, классы от которых зависит, методы, свойства и события. У интерфейса только список методов. Например плагин имеет уже совсем другие свойства: имя, автор, копирайты и так далее. С плагином на самом деле проще - его свойства есть в файле about.ini, но проблема в почти полном отсутствии пересекающихся свойств с классом. Иными словами получается, что система документации будет документацией по классам, и практически это безусловно так. Но кроме классов, как я уже написал, имеются другие типы документов.

Далее у класса имеются неопределенное количество методов, свойств, событий. Их необходимо добавлять/редактировать/удалять. Как быть? Писать форму управления списками? не хочу в виду больших трудозатрат и отсутствии очевидного удобства, так как для этого придется еще дополнительно учится работать в менеджере списков методов/свойств/событий. Я уже неоднократно выдвигал идею про псевдо ini формат описания документа Правда одно другое не исключает - можно сделать форму управления списками и генерировать/парсить ini документ.

Постараюсь формализовать сущность метод/свойство/событие. Во первых у него есть название и он принадлежит одному конкретному классу. Далее список аргументов для методов и событий, для свойств - тип свойства (ну там число, строка...). Индивидуально у методов есть степень видимости (public, protected, private), у свойств уровень доступа (и/или чтение/запись). также у каждой этой сущности есть описание.

Таким образом получается, что если делать формы для каждого случая, то это будет более чем накладно и скорее всего запутано, плюс в будущем модификации/добавления сделают эту работу титанической и в определенном смысле бесполезной. Я склоняюсь к псевдоязыку описания документа аля ini файл. Вариант с xml не рассматривается в виду нередактируемости в ручную xml - там легче легкого наделать ошибок в разметки, и однозначно некая часть времени будет уходить на правку ошибок. С ini проще - он более понятен человеку. Следовательно задача построения документации сводится к ппарсингу формата и генерации на его основании законченного html.

Для меня пока остается одна неопределенность - имена методов/свойств/событий и вики слова. Очевидно, что на имена надо вешать линки, автоматически с этим справляется плагин вики слов. Но вот смоделирую ситуацию: в описании мне надо сослаться на свойство другого класса, то как мне это сделать? Просто написав имя свойства, то будут пролинкованы все свойства/методы/события с этими линками. Требуется точечная адресация. Быть может расширить синтаксисе вики слов до формата [class:someprop]? Тогда бы создавались бы два линка: на общее слово и на слово в документе. Но это неправильно, если посмотреть устройство вики слов, то любым словом может владеть любое количество постов. Под постом здесь (в контексте системы документации) понимается документ. Значить задачу надо переформулировать по другому: как указать линк на слово в посте? При условии неопределенности: неизвестно существует ли такой пост или еще нет, а если существует, то есть ли в нем такое слово? Декларация слова выглядит как [wiki:слово]. Плагин вики добавляет в базу слово для этого поста. То есть следует добавить в систему документации функцию вики слов со второй координатой - имени класса.

Обычные вики слова похожи на прямую, где точки - это слова. С именем класса добавляется вторая координата, и вики слова вырастают до плоскости, где X и y это будут слова и имена классов. Я не знаю, следует ли эту модель адресации к вики словам добавить в плагин вики слов, либо сделать частью системы документации. Предположу, что добавление второй координаты для плагина вики слов может только ввести в заблуждение рядового юзверя, то сделаю это фичей системы документации.

Вот примерно в таком виде я доделаю систему документации.