View
67
Download
4
Category
Preview:
DESCRIPTION
Как мы документируем программные интерфейсы
Citation preview
Как мы документируем программные интерфейсы
│ С какими API и SDK нам │ приходится сталкиваться │ в Яндексе, какие методики │ и инструменты мы используем │ и как генерируем документацию │ из кода
Генерируем документацию
WEB Mobile • Java • Objective-C • C# | C++
│ Javascript
│ HTTP
│ Java
│ Objective-C
│ C# | C++
/** Размечаем код */
Получаем результат
…
Что нам надо
│ Всё и правильно
│ DITA
│ Максимальный контроль
JavaScript. JSDoc
│ Всё и правильно — Да
│ DITA — Да
│ Максимальный контроль —Да
│ Данные — обычные │ {объекты:JavaScript}
│ Преобразование — │ шаблонизатор
│ Вызов шаблонов из JavaScript │ и JavaScript из шаблонов
JSDoc. Генерация ... <if test="data.exceptions.length"> <p translate="no"> <b>{+ (JSDOC.opt.D.lang == "ru" ? "Выбрасывает: " : "Throws: ") +}</b> </p> <dl> <for each="item" in="data.exceptions"> <dlentry> <dt translate="no"> {+ ((item.type)?" {"+(new Link().toSymbol(item.type))+"} " : "") +} {+ item.name +} </dt> <dd>{+ resolveLinks(item.desc) +}</dd> </dlentry> </for> </dl> </if> … Это похоже на Node.js
JSDoc. Результат
Mobile / Multilanguage
Несколько языков Java Objective-C C# | C++
«Одна» библиотека на нескольких языках
Нужен комбайн
│ Всё и правильно — Более │ менее
│ DITA — Да
│ Максимальный контроль — Да
│ Данные — <XML-файлы />
│ Преобразование — XSLT- │ шаблоны
│ Вызов шаблонов из Java │ и Java из шаблонов
Mobile / Multilanguage. Doxygen
Doxygen XML. Генерация
... <xsl:if test="$fields/memberdef"> <topic id="field_detail"> <title translate="no"> <xsl:value-of select="arina:getLocString('Field Detail')"/> </title> <body> <xsl:apply-templates select="$fields/memberdef[@kind='variable']"> <xsl:sort select="name"/> </xsl:apply-templates> </body> </topic> </xsl:if> ...
Doxygen XML. Результат
Doxygen надо проверять
Некорректно обрабатывал наследования при использовании generic-конструкций
public class FloatList extends ArrayList<Float>{...}
Исправлено.
http://www.stack.nl/~dimitri/doxygen/support.html
HTTP. Multilanguage http { server { location /one { # configuration for processing URIs with '/one' — Node.js ... }
location /two { # configuration for processing URIs with '/two' — Java ... }
location /three { # configuration for processing URIs with '/two' — Perl … }
} }
HTTP. Растворено в коде
var express = require('express') var app = express(); … app.get('/one', function(request, response) {
- // что-то происходит с request и response }); }); ...
HTTP. Что делать?
│ Схемы. WADL (<wadl:doc/>), WSDL 2.0 (<documentation/>)
│ Метаописания. Swagger. Песочницы
│ Соглашения. Программирование
Спасибо за внимание
mironov@yandex-team.ru mironovalexey
Алексей Миронов
руководитель группы документирования программных интерфейсов
Recommended