Что Вы рассматриваете хорошей документацией API? [закрытый]

Мне очень нравится Документация Qt4 , она сначала предоставляет вам только важную информацию, необходимую для работы, а если вы хотите копнуть глубже, она раскрывает все кровавые подробности в подразделах.

Что мне действительно очень нравится, так это то, что они встроили всю документацию в Qt Creator, который предоставляет контекстно-зависимую справку и короткие примеры, когда они вам нужны.

На самом деле документация для iPhone (на самом деле Mac Cocoa / framework) стала довольно хорошей. Мне нравятся следующие функции:

• Очень простой переход к документации из API.

• Хорошее форматирование и фрагменты кода. вы хотите скопировать и вставить (например, сигнатуры методов).

• Ссылки на проекты с образцами кода прямо из документации.

• Механизм автоматического обновления документа, но по умолчанию все документы локальны для начало (чтобы можно было жить с ненадежным подключение к Интернету).

• Простой способ переключения между вариантами документации (чтобы увидеть разные версии ОС), а также выберите какие комплекты документации запустить выполняет поиск.

• В обзорном разделе объясняется, что класс для, за которым следует раздел методы выделения, сгруппированные по цель (методы создания и объект, методы для запроса данных, методы работы с шрифтом конверсии и т. д.), а затем подробные объяснения методов.

Мне также лично очень понравился Javadoc и документация по системе Java (я использовал это много лет), я обнаружил, что преимущество в том, что было немного проще создавать собственные пользовательские документы для ваших собственных классов, которые текут хорошо с системной документацией. XCode позволяет вам также использовать Doxygen для создания документации для ваших собственных классов, но потребуется немного больше работы, чтобы отформатировать ее, а также документы системного класса, отчасти потому, что к документам системной инфраструктуры применяется большее форматирование.

Go to the Doxygen site and look at the examples of the HTML that it generates. Those are good:

http://www.doxygen.nl/results.html

My main criteria is - tell me everything I need to know and everything I'll ever want to know.

QT has pretty decent docs: http://doc.qt.digia.com/4.5/index.html

Win32 MSDN is also pretty good although it didn't age well.

The java docs are horrible to me. They constantly tell me everything I don't want to know and nothing of what I do want to know. The .NET docs has a similar tendency although the problem there is mostly the extreme wordyness, overflow of so much superfluous details and so much god damn pages. Why can't I see both the summary and the methods of a class in the same page?

Хороший API-интерфейс будет обладать следующими характеристиками:

• Простота изучения
• Простота использования даже без документации
• Трудно использовать не по назначению
• Легко читать и поддерживать код
• Достаточно мощный для удовлетворения требований
• Легко расширяется
• Соответствует аудитории

Самая распространенная ошибка, которую я вижу в дизайне API, - когда разработчики считают, что автоматически сгенерированного XML-комментария достаточно, а затем предшествовать для автоматического создания своего API на основе комментариев XML. Вот о чем я говорю:

///<summary>
/// Performs ObscureFunction to ObscureClass using ObscureArgument
///</summary>
void ObscureClass.ObscureFunction(ObscureArgument) { ... } 

API, подобные приведенному выше, только контрпродуктивны и расстраивают разработчика, использующего API. Хорошая документация по API должна давать разработчикам подсказки относительно того, как использовать API, и давать им представление об определенных аспектах API, которые в противном случае они бы не заметили.

Хорошая документация должна содержать как минимум следующее:

• Если аргумент имеет дополнительные ограничения помимо его типа, они должны быть полностью указаны.
• Описание [обязательного] состояния объекта перед вызовом метода.
• Описание состояния объекта после вызова метода.
• Полное описание информации об ошибках, предоставляемой методом (возвращаемые значения, возможные исключения). Простое наименование недопустимо .
  • Хороший пример : выдает исключение ArgumentOutOfRangeException, если индекс меньше 0 -или- индекс больше или равен Count .
  • Плохой пример: возвращает 0 в случае успеха или один из следующих E_INVALIDARG и т. Д. (Без указания причины, по которой аргумент является недействительным). Это стандартный подход «разработчика FU», принятый в SDK для PS3.

Кроме того, полезно следующее:

• Описание состояния объекта, если метод вызывает исключение.
• Лучшие практики относительно классов и групп классов (например, для исключений в .NET) в API.
• Пример использования.

На основании этого:

• Примером отличной документации является библиотека MSDN.
  • Честно говоря, онлайн-версия этой документации страдает от трудности навигации в футлярах.
• Примером ужасной документации является PS3 SDK. Изучение API требует обширного тестирования аргументов метода для предположения, что может быть, а что не может быть фактическими требованиями и поведением того или иного метода.

Мне нравится документация Twitter . На мой взгляд, хороший API обновлен, легко читается и содержит примеры.

Я лично считаю, что прекрасным примером хорошей документации является документация PHP:

Например: http://www.php.net/manual/en/function.fopen.php

Я думаю, что эффективная документация включает:

• Список параметров
• (Полезное) описание параметра
• Если параметры являются строкой, перечислите и ОБЪЯСНИТЕ все возможные возможный параметр
• Возвращаемые значения как при успешном выполнении, так и при неуспешном выполнении
• Любые исключения / ошибки, которые он может вызвать
• Примеры (САМОЕ ВАЖНОЕ imo)

Необязательно :

• Список изменений
• Примечания / Примеры от других пользователей

Всякий раз, когда я ищу что-нибудь в документации PHP, я почти точно знаю, как это использовать, без необходимости рыскать по Интернету в поисках «лучших» примеров. Обычно единственный раз, когда мне нужно искать в Интернете, когда мне нужно найти, как использовать набор функций для определенной цели. В остальном, я считаю, что документация PHP - лучший пример отличной документации.

То, что считается примером хорошей документации, - это Python: http://docs.python.org/py3k/library/array.html

В нем перечислены методы, но он не очень хорошо объясняет, что это такое и как его использовать. Особенно если сравнивать с документами PHP.

Первое, что нужно для хорошей документации по API, - это хорошее название самого API. Названия методов и параметров должны быть понятны всем. Если рассматриваемый язык является статически типизированным, используйте перечисления вместо констант String или int в качестве параметров, чтобы выбрать между ограниченным набором вариантов. Какие варианты возможны, теперь можно увидеть в типе параметра.

«Программная часть» документации (текст, а не код) должна охватывать пограничные случаи (что произойдет, если я укажу null в качестве параметра), а документация класса должна содержать пример использования.

Единственным критерием качества документации является то, что она ускоряет разработку. Если вам нужно узнать, как что-то работает, вы идете читать документы. Один документ лучше другого, если вы все поняли из первого документа быстрее, чем из второго.

Любые другие качества субъективны. Стили, перекрестные ссылки, описания… Я знаю людей, которые любят читать книги. Документ в стиле книги (с содержанием / указателем / и т. Д.) Ему подойдет. Другой мой друг любит документировать все внутри кода. Когда он скачивает новую библиотеку, он получает исходники и «читает» их вместо документов.

Мне лично нравится JavaDocs. Как и документация разработчиков Apple, за исключением частей нижнего уровня, например, среда выполнения Obj-C (справочная часть) описана ужасно. Мне также нравятся некоторые API-интерфейсы веб-сайтов.

Не нравится MSDN (в целом это хорошо, но существует слишком много вариантов одного и того же документа, я часто теряюсь).

Мне нравится, когда документация имеет краткий обзор вверху, полнофункциональные примеры внизу и обсуждения под ними! Я удивлен, что мало кто включает простые аргументы функций с их необходимыми типами переменных и значениями по умолчанию, особенно в php!

Боюсь, что я не могу привести пример, потому что я не просмотрел все, чтобы найти мои любимые, однако я знаю, что это, вероятно, не считается, потому что это неофициальная вики, но Kohana 3.0's Unofficial Wiki By Kerkness просто великолепна! и Kohana 2.34 documentation тоже довольно хорошо изложена, по крайней мере, для меня. Что вы думаете, ребята?

Я думаю, что хороший документ по API должен четко объяснять:

1. Какую проблему решает этот API
2. Когда вы должны его использовать
3. Когда вы не должны его использовать
4. Фактический код, показывающий "лучшую практику" использования API

Не совсем документация по API, но тем не менее весьма полезная - это документация по базе данных Oracle, например, для оператора SELECT. Мне нравится включение диаграмм, которые помогают прояснить использование, например.

Большинство людей перечислили пункты, составляющие хорошую документацию по API, поэтому я не собираюсь их повторять (спецификации типов данных, примеры и т. Д.). Я просто приведу пример, который, как мне кажется, иллюстрирует, как это должно быть сделано:

Блок приложения Unity (перейдите в раздел загрузки для CHM)

Все люди, участвующие в этом проекте, сделали отличная работа по документированию этого и того, как его следует использовать. Помимо справочника по API и подробного описания метода, есть много статей и примеров, которые дадут вам общую картину, почему и как.Проекты с такой хорошей документацией редки, по крайней мере, те, которые я использую и о которых знаю.

Несколько мыслей ...

1. Примеры - документация Win32 API лучше, чем у iPhone, потому что:

   • (короткие) примеры кода {{ 1}}
     
     

   Я голосую за любой документ API с небольшими и понятными примерами

2. Никогда не показывайте «Form1», «asdf», «тестирование пользователей» на снимках экрана или образцах кода

   • хорошо API решает проблемы реального мира, и здесь должно быть несколько содержательных примеров
     
     

3. Запрещается автоматическое создание документа

   • Документация не должна выполняться во время написания кода (или тем же человеком)
   • doc для незнакомца, о котором программисты обычно не заботятся
     
     

4. Избегайте ___V2 версии API

   • , но это не проблема документации

Документация - это только часть общей картины, дизайна API. И можно утверждать, что последнее гораздо важнее, чем просто именование. Подумайте о значимых, не дублирующих друг друга именах методов и т.д.

Я бы определенно рекомендовал посмотреть презентацию Джоша Блоха об этом: http://www.infoq.com/presentations/effective-api-design ИЛИ http://www.youtube.com/watch?v=aAb7hSCtvGw

Это охватывает не только то, что вы ищете, но и многое другое.

Вот очень плохая документация: Диспетчер данных . Dispatch - это библиотека Scala для HTTP, которая абстрагируется от библиотеки HTTP (Java) Apache Commons.

Он использует много функционально-синтаксической магии, с которой не все будут хорошо разбираться, но не дает четкого объяснения ни этого, ни стоящих за ним дизайнерских решений. Scaladocs бесполезен, потому что это не традиционная библиотека в стиле Java. Чтобы действительно понять, что происходит, вам в основном нужно прочитать исходный код и прочитать множество сообщений в блогах с примерами.

Документация заставляет меня чувствовать себя глупо и неполноценно, и уж точно не помогает мне делать то, что мне нужно. Оборотная сторона - это большая часть документации, которую я вижу в сообществе Ruby - как в RDoc, так и в FAQ / сайтах / и т. Д. Не делайте просто Javadoc - вам нужно предоставить более полную документацию.

Ответьте на вопрос: «как мне сделать X с Y?» Возможно, вы знаете ответ. Я не.

Я считаю API Google прекрасным примером API хорошей документации.

У них есть:

1. Обзор всей структуры API с высоты птичьего полета
2. Обзор основных функций единого API
3. Красивые цветные примеры для быстрой обратной связи
4. Подробные ссылки
5. Блог которые держат вас в курсе
6. группы Google , которые документируют проблемы и решения
7. Видео
8. FAQ
9. Статьи
10. Презентации
11. Площадка для кода
12. Поисковая система для сканирования внутри кучи документации

Вот и все! Когда я играю с сайтом документации API Google, я чувствую себя как дома.

IMO примеры - лучшая документация.

Обязательно наличие множества практических примеров из реальной жизни. Недавняя переработка документации API jQuery является хорошим примером, как и легендарные документы Django.

В общем, расскажите историю класса на уровне класса. Почему это здесь? Что он должен делать? Что здесь должно быть? Кто его написал?

Расскажите историю методов на уровне методов. Что это делает? Неважно, насколько точны названия ваших методов, 20-30 символов не всегда достаточно для описательности.

@author:

• Кто это написал? Кто этим гордится? Кому должно быть стыдно за свою работу?

Документация уровня интерфейса говорит мне:

• что это должно делать?
• что оно вернет?

Документация уровня реализации говорит мне:

• как это делается? какой алгоритм? какая нагрузка на систему?
• какие условия могут вызвать проблему? вызовет ли нулевой ввод проблему? можно ли использовать отрицательные числа?

Документация уровня класса говорит мне:

• что здесь идет? какие методы я должен ожидать найти?
• что представляет этот класс?

@Deprecated говорит мне:

• почему это планируется удалить?
• когда ожидается удаление?
• какова предлагаемая замена?

Если что-то окончательное:

• почему вы не хотели, чтобы я расширил это?

Если что-то статическое:

• напомните мне об этом в документации на уровне класса, по крайней мере, неявно.

В общем: вы пишете это для следующего разработчика, который будет использовать это, если и когда вы выиграете в лотерею. Вы же не хотите чувствовать себя виноватым за то, что уволились и купили яхту, поэтому уделите немного внимания ясности и не думайте, что вы пишете для себя.

В качестве побочного эффекта, когда кто-то попросит вас поработать с тем же кодом через два года, а вы все забудете, вы получите огромную пользу от хорошей документации в коде.

Одна вещь, которую я всегда хотел видеть в документации: абзац с «обоснованием» для каждой функции или класса.Зачем нужна эта функция? Для чего это было построено? Что из этого не может быть достигнуто другим способом? Если ответ «ничего» (а так бывает на удивление часто), то что это за сокращение и почему эта вещь достаточно важна, чтобы иметь свою собственную функцию?

Этот абзац должен быть легким в написании - если это не так, это наверное признак сомнительного интерфейса.

Лучшая документация, которую я нашел, - это Python . Вы можете использовать sphinx для создания исходной документации в HTML, LaTeX и других форматах, а также для создания документов из исходных файлов; Документ API, который вы ищете.

Документация API - это не только качество окончательной документации, но и то, насколько легко разработчикам и / или техническим писателям действительно ее написать, поэтому выберите инструмент, который упростит работу.

Недавно я обнаружил это документация (библиотека Lift JSON), которая кажется хорошим примером того, о чем просили многие: хороший обзор, хороший пример, варианты использования, намерения и т. Д.