Как мы документируем программные интерфейсы. Алексей Миронов

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

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

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

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

[email protected] mironovalexey

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

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

Technology

Как мы документируем программные интерфейсы. Алексей Миронов