Несмотря на объявление стабильной версии, до сих пор находятся мелкие баги и вносятся изменения. Например планируется подправить инсталлятор - в нем будут новые страницы первой формы установки и приветствия после успешной инсталляции. Также необходимо как то доделать виджет мета - все никак не приму решение, так как каждый из вариантов мне не нравится, а красивого так и не придумывается. Но пост то я озаглавил - документация. О ней и пойдет речь.

Для полноценного запуска сайтов litepublisher.ru(.com) по мимо тикет системы (которая требует отдельного тестирования), я планирую выложить на страницах весь исходный код пблоголёта. Для сырцов я пока решил использовать посты - заголовок (title) как раз и будет именем файла, а контент - контент этого файла. Прикрутил для этого подсветку синтаксиса на javascript. Почему посты? К ним можно оставлять комменты, но вопрос - нужны ли вообще комменты для сырцов для меня не ясен. Предположу, что уже написана и работает подсистема сырцов. Перейду опять к документации.

Документ будет расширенным постом, в котором указано имя файла, имя родителя (тоже не понятно то ли id то ли текст указывать, если id, то нужен комбобокс, а его делать мне не хочется). Также список дочерних классов. Родители дочерние классы должны быть обязательно с линками. В блоголёте есть уже класс отлично справляющийся со списком названий - метки (они же рубрики). Нет проблем, чтобы добавить еще один класс - имена классов, так сказать метки , в которых только имена файлов. Минус метки - то, что она метка, а не пост, и соответственно метку нельзя комментировать, и метка содержит в себе посты. То есть необходимо не промежуточное звено между постами в в виде меток, а необходимо связать посты между собой непосредственно. Как это сделать? В блоголёте сейчас отсутствует подобный класс или механизм. Сформулирую задачу - необходимо свойство у поста, в котором перечислены id других постов. Это свойство должно конвертироваться, в общем случае, в html ссылок на посты -как я уже и писал подобие меток. Ок, задача поставлена, а значит она будет реализована. Поскольку я вроде как объявил о стабилизации версии, то эту функциональность придется вынести за рамки существующего движка, а говоря по русски - реализовать в плагине. И так, предположу, что такое свойство реализовано.

Для документа еще необходимо указать исходник, а по простому проставить линк на пост с исходником (об этом писал чуть выше). Собственно, задача сводится как раз к списку связанных постов - в списке будет всего один пост с файлом Также следует в документе про класс указать по мимо родственных отношений, интерфейсов, также и зависимости - классы которые зависят от описываемого, а также от каких классов этот класс зависит, ну а по простому - кто кого использует.. Тоже получаются перекрестные ссылки друг на друга. Так что в свойстве списка постов появляется все больше потребности.

далее документ состоит из трех частей - методы (публичные и защищенные, приватные не нужно указывать в документации), свойства (а также уровень доступа к ним - только чтение, только запись, оба), события, а также короткий пример php кода, использующий этот класс. На названия методов, свойств и событий можно навесить метки - у некоторых классов совпадают имена, но особой пользы в этом не будет. Тут скорее нужна общая коллекция всех имеющихся в движке методов, свойств и событий. Типа список постов в лайт режиме, когда на одной странице выводился бы перечень всех этих составляющих. Как это сделать мне пока не понятно. Чтобы были ссылки необходимо существование специального урла, а генерировать урл для каждой мелкой сущности нет никакого смысла - описание метода или свойства может и не занимать целой строки. Необходима коллекция внутристраничных ссылок с возможностью автоматического их размещения в других местах. Вот даже сейчас придумал - список классов, а возле имени класса аяксовые ссылки на методы., свойства и события, по которым погружается (раскрывается - не обязательно подгружать) соответствующий список. Этот список должен автоматически генерироваться. Необходима новая сущность - внутристраничные ссылки в посте, разделенные по типам (в моем случае будет 3 типа: методы, свойства и события). И так требуется еще одна новая сущность. Подумаю как быть с ней.

Чтобы упорядочить все внутристраничные ссылки их необходимо каким либо образом собрать. Вариант с парсингом html я не принимаю, так как на мой взгляд необходимо более простое средство. Иными словами требуется язык для описания документа. Если не язык, то формочка в админки с кучей полей редактирования. лирическое отступление: подумалось, что хорошо бы в описании методов и свойств поставить линки на исходник, но не вообще на пост с исходником, а именно на внутристраничную ссылку с исходником конкретного метода. Вопрос о ручном проставлении подобных ссылок даже не рассматривается. необходимо автоматическое средство проставления подобных ссылок. Также еще одно лирическое: и вообще хорошо бы свернуть текст исходника до названий методов класса. По клику на названии появлялся бы его исходник. Сворачивание должно быть после загрузки страницы, чтобы полный текст файла был доступен для индексирования поисковиками. Следовательно необходим несложный парсер сырцов. Предположу, что такой парсер сделал (это не сложно по фразе например public function вычленить начало метода и по количеству фигурных скобок { } найти конец метода. Ну тогда встает вопрос о целесообразности использования синтаксической подсветки на базе javascript - тогда надо будет и синтаксическую подсветку делать средствами php.

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

RSS комментарии к этой записи Рубрики: Идеи