Проект:Технические работы/Шаблоны/Документирование: различия между версиями

На страницу задокументированного шаблона ставится пометка <code><nowiki><&lt;noinclude></nowiki>{{t|doc|b}}<nowiki><&lt;/noinclude></nowiki></code>. При этом создаётся ссылка на страницу документации. После написания документации на соответствующей странице ссылка автоматически будет заменена документацией. Обратите внимание, что редактирование документации не вызовет перерисовки всех страниц, использующих шаблон.

* Чем уже сфера применения шаблона, тем хуже скоординирована работа над ним между разными участниками. Для шаблонов, не отличающихся большим вниманием к себе, можно прямо в тексте документации создаватьсоздать раздел «Необходимо{{sp/}}Можно сделать», где описыватьописать насущные потребности. Если вы считаете, что необходимо внести какое-то изменение в малоизвестный шаблон, но в обсуждении никто не отвечает, этим тоже можно поделиться со «случайными гостями» на странице документации.

* Есть несколько способов представлятьпредставить код примеровпримера использования шаблоновшаблона (или ихего синтаксиса) в документации. Это:

** тег {{tago|pre}}, создающий большие поля вокруг кода. Это единственный возможный способ оформления примеров использования многострочных шаблонов. Этот тег не позволяет использовать вики-разметку внутри себя, а поэтому, если разметка необходима, нужно либо, вместо использования {{tago|pre}}, начинать первуюкаждую строку примера с пробела, либо использовать шаблон {{t|pretpre}} (это удобно для однострочных шаблонов).{{pb

}}Чтобы подсветить места использованиякод шаблона ввнутри длинномдлинного кодекода, используйте шаблон {{t|highlight}} или {{t|oncolor}} (так сделано, например, в документациях шаблонов {{t|переход}} и {{t|ref+}}). Пример синтаксиса однострочного шаблона, оформленного с помощью шаблона {{t|pretpre}}:{{pretpre|t=[[t:перенесено с|перенесено с]]|''Вики-страница''{{optp|''подпись и/или текст в конце''|текст{{=}}''Текст вместо «Перенесено со страницы»''}}}}

}}Чтобы не писать в примерах использования шаблонов каждый раз длинную конструкцию <code><nowiki><code>&lt;nowiki>&lt;/nowiki></code></nowiki></code>, воспользуйтесьможно воспользоваться шаблоном {{t|tc}} и аналогичными (см. ссылки в «См. также» его документации). Для вывода примеров вызовавключения шаблона рядом с кодами вызовавключения можно использовать шаблон {{t|пример}} и аналогичные (в том числе {{t|стопка примеров}}, {{t|таблица примеров}}; покликайте по ссылкам в разделах «См. также»).{{pb

}}Пример синтаксиса шаблона, оформленного с помощью шаблона {{t|tc}}:{{pb

* Существуют разные способы представить синтаксис шаблона (в понятие «синтаксиса» здесь входит только список параметров и их обязательность, хотя, если понимать это шире, это будет включать тип/формат данных, значение по умолчанию, зависимости параметров, возможность загрузки из Викиданных и пр.прочее). Можно перечислить варианты обращения к шаблону в столбик, как сделано в документации шаблона {{t|флаг}}, а можно представить единой записью, как в документации шаблона {{t|перенесено с}}. Часто хорошая идея — дать «базовый» и «продвинутый» вариант записи (а ещё бывает «минимальный», «рекомендуемый», «полный»…). НеПри путайтеэтом прине этомпутайте ''демонстрациюпредставление синтаксиса шаблона'' с ''примером его использования''. Один из возможных вариантов оформления синтаксиса единой записью представлен на странице {{ссылка на раздел|Шаблон:Tc#В оформлении документации}}.

* Ещё одна мелочь — как в коде вызовавключения многострочных шаблонов отбивать вертикальные черты от начала строк, а названия параметров — от вертикальных черт. В английском разделе часто либо нет отбития вовсе, либо отбиваются названия параметров от вертикальных черт на один символ. У нас в этом деле разнобой.{{pb