Как мы документируем программные интерфейсы. YaC 2014

Как мы документируем программные интерфейсы

│ С какими 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://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. Песочницы

│Соглашения. Программирование

Спасибо за внимание

[email protected] mironovalexey

Алексей Миронов

руководитель группы документирования программных интерфейсов

Technology

Как мы документируем программные интерфейсы. YaC 2014