|
Модераторы: Cheba |
|
Любитель |
|
|||
Программист-романтик Профиль Группа: Комодератор Сообщений: 3645 Регистрация: 21.5.2005 Где: Воронеж Репутация: 2 Всего: 92 |
При написании документации достаточно часто описывается некоторый элемент (класс, структура, модуль, пространство имён, пакет и т. д.) и его подэлементы. При этом в нормальной документации очень часто делают так:
1. Вначале пишется структура этого элемента с подразделами (вроде паблик, прайват и т. д.) локальными (в пределах страницы) ссылками на подробное описание. 2. Затем идёт более подробное описание элемента. 3. После подэлементы с более подробным их описанием. При этом при описании подэлементов есть стандартные разделы. Вроде возвращаемого значения, списка аргументов, исключений, предусловий и т. д. Наиболее естественным методом написания документация в подобном стиле будет использование подразделов, но отображаться это будет совсем не так как хочется. Хотелось бы что-то типа такого:
Это, кончено, тупой пример, да и синтаксис оставляет желать лучшего. Но я думаю общими усилиями можно придумать нечто удобное и всех многих устраивающее. Кроме того хорошо бы иметь специальный синтаксис для ссылок внутри документации на документируемые элементы (например, MyError). Ещё раз подчёркиваю, что этот пример выражает лишь суть идеи, а не заказ на определённый синтаксис. В общем придётся поработать (и над утверждением синтаксиса), и над расширением, но результат по-моему того стоит. В противном случае (если не найдётся тех, кто поддержит мою идею) надо хотя бы создать (и потом опубликовать) какие-то единые правила. Это сообщение отредактировал(а) Любитель - 23.9.2006, 20:33 |
|||
|
||||
Cheba |
|
|||
pointless one Профиль Группа: Vingrad developer Сообщений: 1777 Регистрация: 27.11.2003 Где: /dev/null Репутация: 6 Всего: 62 |
В чем суть идеи? Я не понял.
Если дело касается структуры и оформления документа, то это все можно сделать с помощью wiki-синтаксиса. |
|||
|
||||
Любитель |
|
|||
Программист-романтик Профиль Группа: Комодератор Сообщений: 3645 Регистрация: 21.5.2005 Где: Воронеж Репутация: 2 Всего: 92 |
Возможно, конечно я плохо знаю разметку. Тогда вопрос - как сделать лоакльную ссылку не на подраздел. К примеру: здесь (пример документации).
И второе (собственно суть идеи) - сделать дополнительный синтаксис, позволяющий автоматом оформлять это в едином стиле. Либо просто официально опубликовать некоторый единый стиль доков. |
|||
|
||||
Cheba |
|
|||
pointless one Профиль Группа: Vingrad developer Сообщений: 1777 Регистрация: 27.11.2003 Где: /dev/null Репутация: 6 Всего: 62 |
Если ты присмотришься, то там ссылки тоже указывают на заголовки. В вики каждый заголовок создает раздел. У каждого раздела есть своя ссылка. Посмотреть ее можно в содержании статьи. О создании ссылок почитай хелп. Например, вот здесь.
|
|||
|
||||
Exception |
|
|||
Эксперт Профиль Группа: Участник Клуба Сообщений: 4525 Регистрация: 26.12.2004 Репутация: 3 Всего: 186 |
Ссылки на отдельные заголовки делаются так: [[Название страницы#Заголовок]]. Насчёт единого стиля - можно было бы сделать шаблон, но тут несколько не то, боюсь, придётся делать расширения.. Гемор.
|
|||
|
||||
Cheba |
|
|||
pointless one Профиль Группа: Vingrad developer Сообщений: 1777 Регистрация: 27.11.2003 Где: /dev/null Репутация: 6 Всего: 62 |
Какие расширения? Я до сих пор не понимаю о чемь речь...
|
|||
|
||||
Cr@$h |
|
|||
Исследователь Профиль Группа: Участник Клуба Сообщений: 1693 Регистрация: 3.4.2005 Где: Санкт-Петербург, Россия Репутация: 2 Всего: 41 |
Да ну. Я сам с трудом понимаю. Не стоит накладывать такие жёсткие рамки. Оформляй все стаьи в едином стиле и всё. К тому же не все статьи будут описывать какой-то класс. Главное выработать у себя дисциплину и следовать ей. Основные рекомендации даны в руководствах Viki.
|
|||
|
||||
Любитель |
|
|||
Программист-романтик Профиль Группа: Комодератор Сообщений: 3645 Регистрация: 21.5.2005 Где: Воронеж Репутация: 2 Всего: 92 |
Енто я, к счастью, понял. Вопрос в другом - ссылка на раздел, так скажем без заголовка. Можно по другому - невидимый заголовок. Иначе говоря, обычные якоря (закладки). |
|||
|
||||
Cr@$h |
|
|||
Исследователь Профиль Группа: Участник Клуба Сообщений: 1693 Регистрация: 3.4.2005 Где: Санкт-Петербург, Россия Репутация: 2 Всего: 41 |
||||
|
||||
Любитель |
|
|||
Программист-романтик Профиль Группа: Комодератор Сообщений: 3645 Регистрация: 21.5.2005 Где: Воронеж Репутация: 2 Всего: 92 |
Всё это означает - заголовок есть в структуре (для адресации), но нет при отображении страницы.
Единый стиль в моём понятии включает: 1. Именование секций. Кто-то напишет "Список исключений", кто-то - "Исключения", кто-то "Throws" и т. д. 2. Оформление секций. Кто-то напишет их жирными, кто-то другим цветом и т. д. Кто-то оформит заголовок секции отдельным параграфом или элементом списка, кто-то - нет и т. д. |
|||
|
||||
Cr@$h |
|
|||
Исследователь Профиль Группа: Участник Клуба Сообщений: 1693 Регистрация: 3.4.2005 Где: Санкт-Петербург, Россия Репутация: 2 Всего: 41 |
Если заголовок в коде вики создан как =...= Заголовок =...=, то в содержании он будет присутствовать и он может якорем выступать. его хорошо бы просто поддерживать один и тот же. Если пришёл новичок, написал что-то и ушёл, то обычно смотритель за разделом должен подвести статью под общий стиль. Есть рекомендации по оформлению статьей, но тонкости, про которые ты говоришь, по-моему, нигде не оговорены. Лучше выработать хороший стиль и применять его на всех страницах. |
|||
|
||||
Любитель |
|
|||
Программист-романтик Профиль Группа: Комодератор Сообщений: 3645 Регистрация: 21.5.2005 Где: Воронеж Репутация: 2 Всего: 92 |
а как сделать, чтобы он не пристутствовал в содержании, т. е. использовался только для ссылки ? |
|||
|
||||
Cr@$h |
|
|||
Исследователь Профиль Группа: Участник Клуба Сообщений: 1693 Регистрация: 3.4.2005 Где: Санкт-Петербург, Россия Репутация: 2 Всего: 41 |
Как тебе сказать.. я не знаю, если честно. Ведь сам посуди:
|
|||
|
||||
Cheba |
|
|||
pointless one Профиль Группа: Vingrad developer Сообщений: 1777 Регистрация: 27.11.2003 Где: /dev/null Репутация: 6 Всего: 62 |
Хитрости не знаю. Практической пользы не вижу.
|
|||
|
||||
Cr@$h |
|
|||
Исследователь Профиль Группа: Участник Клуба Сообщений: 1693 Регистрация: 3.4.2005 Где: Санкт-Петербург, Россия Репутация: 2 Всего: 41 |
Можешь ещё просто содержание отключить: __NOTOC__
Но это рекомендуется делать только на заглавных страницах. |
|||
|
||||
0 Пользователей читают эту тему (0 Гостей и 0 Скрытых Пользователей) | |
0 Пользователей: | |
« Предыдущая тема | wiki.vingrad.ru | Следующая тема » |
|
По вопросам размещения рекламы пишите на vladimir(sobaka)vingrad.ru
Отказ от ответственности Powered by Invision Power Board(R) 1.3 © 2003 IPS, Inc. |