Повторное использование текста документации
<inheritdoc>
Наследование XML-комментариев от базовых классов, интерфейсов и аналогичных методов. Использование позволяет обойтись без копирования и вставки одинаковых XML-комментариев и автоматически поддерживать их синхронизацию
Обратите внимание, что при добавлении тега к типу все члены также будут наследовать эти комментарии
- : укажите член для наследования документации. Унаследованные теги не переопределяют уже определенные теги для текущего элемента.
- : запрос с выражением XPath, в результате которого выводится набор узлов. С помощью этого атрибута можно отфильтровать теги, которые следует включить в наследуемую документацию или исключить из нее.
Добавьте XML-комментарии в базовые классы или интерфейсы, и InheritDoc скопирует их во все реализации классов. Добавьте XML-комментарии в синхронные методы, и InheritDoc скопирует их в асинхронные версии аналогичных методов. Если нужно скопировать комментарии из определенного элемента, укажите нужный элемент в атрибуте .
<include>
- : имя XML-файла, содержащего документацию. Имя файла может быть квалифицировано с помощью относительного пути к файлу исходного кода. необходимо заключать в одинарные кавычки (‘ ‘).
- : путь тегов в , который ведет к тегу . Путь необходимо заключать в одинарные кавычки (‘ ‘).
- : спецификатор имени в теге, предшествующий комментариям. будет иметь идентификатор .
- : идентификатор тега, который предшествует комментариям. Идентификатор заключается в двойные кавычки (» «).
Тег позволяет задать ссылку на комментарии в другом файле, которые описывают типы и элементы вашего исходного кода. Включение внешнего файла является альтернативой размещению комментариев документации непосредственно в файле исходного кода. Помещая комментарии документации в отдельный файл, вы можете реализовать управление их версиями отдельно от версий исходного кода. В этом случае файл исходного кода может быть извлечен для изменения одним пользователем, а файл документации — другим. Тег использует XML-синтаксис XPath. Сведения об использовании тега см. в документации по XPath.
Example HTML code 2:
This example illustrates the use of the param element with Macromedia Flash Player. It clearly focuses on cross-browser support only, and it isn’t standards-compliant, but there isn’t any standards-compliant cross-browser way to embed a Flash application into a document with Flash Player detection.
<objectclassid="clsid:d27cdb6e-ae6d-11cf-96b8-444553540000"width="300"height="120"codebase="http://fpdownload.adobe.com/pub/shockwave/cabs/flash/swflash.cab#version=9,0,0,0"><paramname="movie"value="flash.swf"/><!-- Optional params --><paramname="play"value="true"/><paramname="loop"value="true"/><paramname="quality"value="high"/><!-- END Optional --><embedsrc="flash.swf"width="300"height="120"play="true"loop="true"quality="high"pluginspage="http://www.adobe.com/shockwave/download/index.cgi?P1_Prod_Version=ShockwaveFlash"/></object> |
|
Did you find this example helpful? yes |
¶Создание списков в документации
Списки в документации начинаются с .
Пример синтаксиса:
Примечания по синтаксису:
- Дефис в качестве первого символа в строке (за исключением ) указывает на элемент списка.
- Все пункты списка одного уровня, должны иметь идентичные отступы.
- Между пунктами не должно быть пустых линий, если они принадлежат одному списку.
- Если в списке требуются ключи, используйте двоеточие между ключом и его описанием. API модуль отформатирует ключи при помощи .
Примечания по Drupal стандартам:
- Строка перед списком должна заканчиваться двоеточием .
- Дефис выравнивается по тексту, содержащий этот уровень списка, это означает, что каждый каждый уровень вложенности отступает на два пробела.
- Ключи массива не помещаются в кавычки; ключи, которые описывают строки (например значения параметров), должны быть помещены в кавычки.
- Помечайте необязательные элементы списки при помощи , а значения по умолчанию при помощи .
Template
Here’s a template for the tag with all available attributes for the tag (based on HTML5). These are grouped into attribute types, each type separated by a space. In many cases, you will probably only need one or two (if any) attributes. Simply remove the attributes you don’t need.
For more information on attributes for this tag, see HTML5 Tag and HTML4 Tag.
<param
name=»»
value=»»
accesskey=»»
class=»»
contenteditable=»»
contextmenu=»»
dir=»»
draggable=»»
dropzone=»»
hidden=»»
id=»»
itemid=»»
itemprop=»»
itemref=»»
itemscope=»»
itemtype=»»
lang=»»
spellcheck=»»
style=»»
tabindex=»»
title=»»
translate=»»
onabort=»»
onautocomplete=»»
onautocompleteerror=»»
onblur=»»
oncancel=»»
oncanplay=»»
oncanplaythrough=»»
onchange=»»
onclick=»»
onclose=»»
oncontextmenu=»»
oncuechange=»»
ondblclick=»»
ondrag=»»
ondragend=»»
ondragenter=»»
ondragexit=»»
ondragleave=»»
ondragover=»»
ondragstart=»»
ondrop=»»
ondurationchange=»»
onemptied=»»
onended=»»
onerror=»»
onfocus=»»
oninput=»»
oninvalid=»»
onkeydown=»»
onkeypress=»»
onkeyup=»»
onload=»»
onloadeddata=»»
onloadedmetadata=»»
onloadstart=»»
onmousedown=»»
onmouseenter=»»
onmouseleave=»»
onmousemove=»»
onmouseout=»»
onmouseover=»»
onmouseup=»»
onmousewheel=»»
onpause=»»
onplay=»»
onplaying=»»
onprogress=»»
onratechange=»»
onreset=»»
onresize=»»
onscroll=»»
onseeked=»»
onseeking=»»
onselect=»»
onshow=»»
onsort=»»
onstalled=»»
onsubmit=»»
onsuspend=»»
ontimeupdate=»»
ontoggle=»»
onvolumechange=»»
onwaiting=»»
>
Event Attributes
HTML tag support following event attributes.
| Attributes | Value | Description |
|---|---|---|
| onfocus | script | element gets focus on object when script tobe run. |
| onblur | script | element lose the focus on object when scrip tobe run. |
| onabort | script | element gets aborted on object when script tobe run. |
| onchange | script | element gets anytime change on object when script tobe run. |
| onbeforeunload | script | element gets unloaded on object when scrip tobe run. |
| onclick | script | clicked on object when script tobe run. |
| ondblclick | script | double click on object when script tobe run. |
| onkeydown | script | key is pressed when script tobe run. |
| onkeypress | script | key is pressed over element then released when script tobe run. |
| onkeyup | script | key is released over element when script tobe run. |
| onmousedown | script | mouse button was pressed over an element when script tobe run. |
| onmouseout | script | mouse pointer release over an element when script tobe run. |
| onmousemove | script | run mouse pointer moved when script tobe run. |
| onmouseover | script | run mouse pointer move over when script tobe run. |
| onmouseup | script | mouse button is released when script tobe run. |
| onreset | script | form has been reset when script tobe run. |
| onselect | script | Select some content when script tobe run. |
| onsubmit | script | form has been submitted when script tobe run. |
| onload | script | object has load when script tobe run. |
| onchange | script | allow to change the object when script tobe run. |
| onunload | script | unload to the browser window when script tobe run. |
| ondrag | script | element being dragged when script tobe run. |
| ondragend | script | element being stop dragged when script tobe run. |
| ondragenter | script | element being go target dragged when script tobe run. |
| ondragleave | script | element being leave to target dragged when script tobe run. |
| ondragover | script | element being over to target dragged when script tobe run. |
| ondragstart | script | element being start dragged when script tobe run. |
| ondrop | script | element being dropped when script tobe run. |
| onerror | script | element error occurs when script tobe run. |
| onmessage | script | element message display when script tobe run. |
| onerror | script | element error occurs when script tobe run. |
| onmousewheel | script | mouse wheel will be rotate when script tobe run. |
| onscroll | script | scrollbar is scroll when script tobe run. |
| onresize | script | element should be resize when script tobe run. |
| onselect | script | all element content selected when script tobe run. |
| onstorage | script | element should be store in target when script tobe run. |
Example HTML code 1:
This example illustrates the use of the param and object elements to embed a Macromedia Flash Movie. The codeBase attribute of the object tag is missing from this example. You can check the version of the user’s Flash player with this attribute in Internet Explorer, and if it does not exist or its version is lower than required, the browser pops up an installation dialog. Unfortunately, the use of the codeBase attribute causes problems in Firefox. See Example 2 for a cross-browser solution or the codeBase attribute for further details.
<objectdata="flash.swf"type="application/x-shockwave-flash"width="300px"height="200px"><!-- If flash player is not installed, pluginurl helps the user to download it in Firefox --><paramname="pluginurl"value="http://www.macromedia.com/go/getflashplayer"/><paramname="movie"value="flash.swf"/><paramname="bgcolor"value="#FFFFE0"/><paramname="quality"value="high"/></object> |
|
Did you find this example helpful? yes |
Attributes
Attributes can be added to an HTML element to provide more information about how the element should appear or behave.
There are 3 kinds of attributes that you can add to your HTML tags: Element-specific, global, and event handler content attributes.
The element accepts the following attributes.
Element-Specific Attributes
This table shows the attributes that are specific to the tag/element.
| Attribute | Description |
|---|---|
| name | Defines the name of the parameter. Required attribute. |
| value | Specifies the value of the parameter. Required attribute. |
Global Attributes
The following attributes are standard across all HTML5 elements. Therefore, you can use these attributes with the tag , as well as with all other HTML tags.
- accesskey
- class
- contenteditable
- contextmenu
- dir
- draggable
- dropzone
- hidden
- id
- inert
- itemid
- itemprop
- itemref
- itemscope
- itemtype
- lang
- spellcheck
- style
- tabindex
- title
- translate
For a full explanation of these attributes, see HTML 5 global attributes.
Event Handler Content Attributes
Event handler content attributes enable you to invoke a script from within your HTML. The script is invoked when a certain «event» occurs. Each event handler content attribute deals with a different event.
Below are the standard HTML5 event handler content attributes.
Again, you can use any of these with the element, as well as any other HTML5 element.
- onabort
- oncancel
- onblur
- oncanplay
- oncanplaythrough
- onchange
- onclick
- oncontextmenu
- ondblclick
- ondrag
- ondragend
- ondragenter
- ondragexit
- ondragleave
- ondragover
- ondragstart
- ondrop
- ondurationchange
- onemptied
- onended
- onerror
- onfocus
- onformchange
- onforminput
- oninput
- oninvalid
- onkeydown
- onkeypress
- onkeyup
- onload
- onloadeddata
- onloadedmetadata
- onloadstart
- onmousedown
- onmousemove
- onmouseout
- onmouseover
- onmouseup
- onmousewheel
- onpause
- onplay
- onplaying
- onprogress
- onratechange
- onreadystatechange
- onscroll
- onseeked
- onseeking
- onselect
- onshow
- onstalled
- onsubmit
- onsuspend
- ontimeupdate
- onvolumechange
- onwaiting
For a full explanation of these attributes, see HTML 5 event handler content attributes.
Основная структура страницы
Как выглядит основная структура html-страницы
Header
Элемент используется для создания шапки всего сайта или шапки отдельных компонентов. Шапка сайта — это блок с вводной информацией, в ней обычно находятся такие элементы как: логотип, меню, кнопки соцсетей, строка поиска и другие ключевые элементы.Чаще всего шапка располагается вверху страницы.
Запись в коде:
Как выглядит header на сайте (желтый цвет)
Довольно часто встречаются случаи когда в помещают контент идущий сразу после шапки (выделенный голубым цветом элемент на скриншоте выше), но правильнее будет поместить его в тег , обернув тегом с классом «hero» Тултип: Так часто называют первую секцию сайта, которую пользователь видит сразу при загрузке страницы .
Main
В элемент помещают главное содержимое — то, которое больше нигде не повторяется на сайте. В элемент main помещаются теги section — разделы сайта. Соответственно, второстепенные элементы сюда не входят: шапка сайта, подвал, боковые панели, ссылки навигации, информация об авторских правах, логотипы сайта, как правило, остаются вне контейнера .
Запись в коде:
Вспомним header из нашего примера, так вот контент идущий после шапки сайта уже будет обернут в тег (кроме footer-а):
Section
Элемент создает блок обертку для разделов сайта — например, цели проекта, функции продукта, партнеры, команда. Тег , как правило, помещается в .
Хороший пример использования — разделение книги на главы, ведь название главы описывает ее содержание. Также одна глава, без остальных, воспринимается вырванной из контекста. То же самое с контентом главной страницы. Смысловые разделы составляют содержание страницы, но сами по себе, в отрыве от страницы, эти «секции» жить не могут и теряют смысл.
Запись в коде:
Как выглядит section на сайте (желтый цвет)
Footer
Элемент создает нижнюю часть страницы или блока — «подвал». Обычно здесь находятся контакты, ссылки на разделы сайта, копирайт. В подвале мы чаще всего видим название компании, правовую информацию, ссылки на соцсети и другие контакты.
Запись в коде:
Как выглядит footer на сайте (желтый цвет)
Aside
Элемент размечает блок с дополнительным содержимым (sidebar). Он может не иметь отношения к главному () контенту сайта. Часто используется для боковой колонки на сайте, в которой может помещаться разделы сайта, реклама и т.д.
Запись в коде:
Как выглядит aside на сайте (желтый цвет)
Как мы можем заметить, не всегда бывает один.
Встраивание элементов
<img></img> — вставка изображения. Имеет атрибут src, который указывает на адрес нужного файла. Есть и другие атрибуты:
<img src=»name» align=?> — выравнивание к одной из сторон документа. Например, значение right переместит рисунок в правый край, а left — в левый.
<img src=»name» border=?> — позволяет настроить в пикселях толщину рамки вокруг изображения.
<picture></picture> — контейнер для расположения элемента <img> без <source>, который даёт браузеру возможность самостоятельно выбрать подходящую картинку.
<audio></audio> — вставка звукового контента.
<video></video> — вставка видео (поддерживается Ogg, WebM и MP4).
<source></source> — указывает местоположение файла для <video>, <audio> и <picture>
<track> — формирует субтитры для <video> и <audio>.
<object></object> — контейнер, через который встраиваются мультимедийные файлы. Для передачи параметров применяется тег <param>.
<hr> — размещает на странице горизонтальную линию. Имеет несколько атрибутов.
<hr size=?> — устанавливает высоту линии.
<hr width=?> — устанавливает ширину линии.
<hr noshade> — убирает тень у линии.
<hr color=?> — задаёт цвет линии.
<script></script> — определяет выполнение сценария на стороне посетителя сайта. Может содержать сам скрипт или иметь ссылку на внешний источник.
<noscript></noscript> — ограничивает фрагмент документа, в котором скрипт не выполняется.
¶Типы данных в документации
Указывайте типы данных в документации (, и т.д.).
Примеры:
Примечания к синтаксису:
- Типы данных могут быть примитивные (int, string, и т.д.), сложные встроенные PHP типы (array, object, resource) или PHP классы.
- Если доступен единственный тип, используйте только его.
- Если доступно несколько возможных типов, разделяйте их вертикальной чертой ().
- Для массивов, содержание которых состоит из одинаковых классов или объектов, указывается полное пространство имён до класса или интерфейса с на конце.
- Массивы состоящие из встроенных PHP типов описываются с на конце.
- Когда вы возвращаете основной объект класса (), используйте .
- Когда создаете новый экземпляр текущего класса, используйте .
Примечания по Drupal стандартам:
- Используйте имена интерфейсов там где это возможно, или максимально общий класс, вместо конкретного класса.
- Всегда используйте полное пространство имён (начинаются с обратного слэша) для классов и интерфейсов.
- Вы можете опустить описание для и .
- Для встроенных в PHP типов используйте следующие имена:
- (НЕ ). Тем не менее, синтаксис приоритетнее, если это допустимо. То есть, если вы знаете что содержит массив и все его элементы данного типа, то указывайте или и т.д., вместо использования общего типа .
- (НЕ или ). Если доступно только значение или , тогда указывайте или вместо вариантивного типа.
- (НЕ )
- (НЕ )
- (НЕ );
- (НЕ )
- (НЕ )
@TODO complete it
@TODO create separete page for https://www.drupal.org/node/1823416
