Как мы документируем программные интерфейсы. yac 2014
DESCRIPTION
Как мы документируем программные интерфейсыTRANSCRIPT
![Page 1: Как мы документируем программные интерфейсы. YaC 2014](https://reader034.vdocuments.site/reader034/viewer/2022052621/557f2db2d8b42ad4798b49d3/html5/thumbnails/1.jpg)
![Page 2: Как мы документируем программные интерфейсы. YaC 2014](https://reader034.vdocuments.site/reader034/viewer/2022052621/557f2db2d8b42ad4798b49d3/html5/thumbnails/2.jpg)
Как мы документируем программные интерфейсы
![Page 3: Как мы документируем программные интерфейсы. YaC 2014](https://reader034.vdocuments.site/reader034/viewer/2022052621/557f2db2d8b42ad4798b49d3/html5/thumbnails/3.jpg)
│ С какими API и SDK нам│ приходится сталкиваться│ в Яндексе, какие
методики│ и инструменты мы
используем│ и как генерируем
документацию│ из кода
![Page 4: Как мы документируем программные интерфейсы. YaC 2014](https://reader034.vdocuments.site/reader034/viewer/2022052621/557f2db2d8b42ad4798b49d3/html5/thumbnails/4.jpg)
Генерируем документацию
WEB Mobile
│Javascript
│HTTP
│Java
│Objective-C
│C# | C++
![Page 5: Как мы документируем программные интерфейсы. YaC 2014](https://reader034.vdocuments.site/reader034/viewer/2022052621/557f2db2d8b42ad4798b49d3/html5/thumbnails/5.jpg)
/** Размечаем код */
![Page 6: Как мы документируем программные интерфейсы. YaC 2014](https://reader034.vdocuments.site/reader034/viewer/2022052621/557f2db2d8b42ad4798b49d3/html5/thumbnails/6.jpg)
Получаем результат
![Page 7: Как мы документируем программные интерфейсы. YaC 2014](https://reader034.vdocuments.site/reader034/viewer/2022052621/557f2db2d8b42ad4798b49d3/html5/thumbnails/7.jpg)
…
![Page 8: Как мы документируем программные интерфейсы. YaC 2014](https://reader034.vdocuments.site/reader034/viewer/2022052621/557f2db2d8b42ad4798b49d3/html5/thumbnails/8.jpg)
Что нам надо
│Всё и правильно
│DITA
│Максимальный контроль
![Page 9: Как мы документируем программные интерфейсы. YaC 2014](https://reader034.vdocuments.site/reader034/viewer/2022052621/557f2db2d8b42ad4798b49d3/html5/thumbnails/9.jpg)
JavaScript. JSDoc
│Всё и правильно — Да
│DITA — Да
│Максимальный контроль —Да
│Данные — обычные│{объекты:JavaScript}
│Преобразование —│шаблонизатор
│Вызов шаблонов из JavaScript
│и JavaScript из шаблонов
![Page 10: Как мы документируем программные интерфейсы. YaC 2014](https://reader034.vdocuments.site/reader034/viewer/2022052621/557f2db2d8b42ad4798b49d3/html5/thumbnails/10.jpg)
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
![Page 11: Как мы документируем программные интерфейсы. YaC 2014](https://reader034.vdocuments.site/reader034/viewer/2022052621/557f2db2d8b42ad4798b49d3/html5/thumbnails/11.jpg)
JSDoc. Результат
![Page 12: Как мы документируем программные интерфейсы. YaC 2014](https://reader034.vdocuments.site/reader034/viewer/2022052621/557f2db2d8b42ad4798b49d3/html5/thumbnails/12.jpg)
Mobile / Multilanguage
Несколько языковJavaObjective-CC# | C++
«Одна» библиотека на нескольких языках
Нужен комбайн
![Page 13: Как мы документируем программные интерфейсы. YaC 2014](https://reader034.vdocuments.site/reader034/viewer/2022052621/557f2db2d8b42ad4798b49d3/html5/thumbnails/13.jpg)
│Всё и правильно — Более│менее
│DITA — Да
│Максимальный контроль — Да
│Данные — <XML-файлы />
│Преобразование — XSLT-
│шаблоны
│Вызов шаблонов из Java│и Java из шаблонов
Mobile / Multilanguage. Doxygen
![Page 14: Как мы документируем программные интерфейсы. YaC 2014](https://reader034.vdocuments.site/reader034/viewer/2022052621/557f2db2d8b42ad4798b49d3/html5/thumbnails/14.jpg)
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>...
![Page 15: Как мы документируем программные интерфейсы. YaC 2014](https://reader034.vdocuments.site/reader034/viewer/2022052621/557f2db2d8b42ad4798b49d3/html5/thumbnails/15.jpg)
Doxygen XML. Результат
![Page 16: Как мы документируем программные интерфейсы. YaC 2014](https://reader034.vdocuments.site/reader034/viewer/2022052621/557f2db2d8b42ad4798b49d3/html5/thumbnails/16.jpg)
Doxygen надо проверять
Некорректно обрабатывал наследованияпри использовании generic-конструкций
public class FloatList extends ArrayList<Float>{...}
Исправлено.
http://www.stack.nl/~dimitri/doxygen/support.html
![Page 17: Как мы документируем программные интерфейсы. YaC 2014](https://reader034.vdocuments.site/reader034/viewer/2022052621/557f2db2d8b42ad4798b49d3/html5/thumbnails/17.jpg)
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 … }
}}
![Page 18: Как мы документируем программные интерфейсы. YaC 2014](https://reader034.vdocuments.site/reader034/viewer/2022052621/557f2db2d8b42ad4798b49d3/html5/thumbnails/18.jpg)
HTTP. Растворено в коде
var express = require('express')var app = express();…app.get('/one', function(request, response) {
// что-то происходит с request и response });});...
![Page 19: Как мы документируем программные интерфейсы. YaC 2014](https://reader034.vdocuments.site/reader034/viewer/2022052621/557f2db2d8b42ad4798b49d3/html5/thumbnails/19.jpg)
HTTP. Что делать?
│Схемы. WADL (<wadl:doc/>), WSDL 2.0 (<documentation/>)
│Метаописания. Swagger. Песочницы
│Соглашения. Программирование
![Page 20: Как мы документируем программные интерфейсы. YaC 2014](https://reader034.vdocuments.site/reader034/viewer/2022052621/557f2db2d8b42ad4798b49d3/html5/thumbnails/20.jpg)
Спасибо за внимание
![Page 21: Как мы документируем программные интерфейсы. YaC 2014](https://reader034.vdocuments.site/reader034/viewer/2022052621/557f2db2d8b42ad4798b49d3/html5/thumbnails/21.jpg)
[email protected] mironovalexey
Алексей Миронов
руководитель группы документирования программных интерфейсов