View
71
Download
0
Category
Preview:
DESCRIPTION
Как мы документируем программные интерфейсы
Citation preview
Как мы документируем программные интерфейсы
│ С какими API и SDK нам│ приходится сталкиваться│ в Яндексе, какие
методики│ и инструменты мы
используем│ и как генерируем
документацию│ из кода
Генерируем документацию
WEB Mobile
│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
Несколько языковJavaObjective-CC# | 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