Мне всегда нравилась документация по API Java, вообще говоря, но я знаю, что некоторые люди считают, что им не хватает. Поэтому мне интересно, что вы считаете хорошим примером документации API?
Пожалуйста, укажите ссылку или фактический пример в любом ответе. Я хочу иметь ссылки, которые я (и другие, конечно) могут использовать для улучшения наших собственных документов.
Хорошая документация ДОЛЖНА иметь:
Я знаю, как рисовать произвольную форму произвольного цвета в GTK+. Я до сих пор не знаю, почему изменение цвета рисования требует трех довольно длинных строк очень неясных, довольно неинтуитивных строк кода. Вспоминая SVGAlib setcolorRGB(r,g,b); draw(x1,y1,x2,y2); Мне очень сложно понять, что у многих авторов GTK + усложняло. Может быть, если они объяснят базовые концепции, а не просто документируют функции, которые их используют, я бы понял...
Другой пример: вчера я получил ответ, который позволил мне понять SQLite. Я понял, что функция, извлекающая данные из столбца, возвращает signed long long. Я понял, что целые столбцы могут быть 1,2,4,6 и 8 байтов. Я понял, что могу определить столбец как "UNSIGNED INT8" или "TINYINT". Я не совсем понял, что означало "близость", я просто знал, что оба имеют "ИНТЕГЕР". Я часами искал, должны ли временные метки быть UNSIGNED INTEGER или INT8, является ли INT8 8-значным или 8-байтовым, и каково имя этого эзотерического 6-байтового int?
То, что я пропустил, состояло в том, что "UNSIGNED INT8", "TINYINT" и т.д. все являются синтаксическими синтаксическими сахарами для типа "INTEGER" (который всегда signed long long), а указанные длины предназначены только для внутреннего дискового хранилища, настраиваются автоматически и прозрачно, чтобы соответствовать любому значению на минимальном количестве бит и полностью невидимы и недоступны со стороны API.
На самом деле документация на iPhone (действительно Mac Cocoa/framework) стала очень хорошей. Мне нравится следующие функции:
Очень легкий переход к документам из API.
Хорошо отформатированные и фрагменты кода вы хотите скопировать и вставить (например, сигнатуры методов).
Ссылки на проекты с образцом кода прямо из документов.
Автоматический механизм обновления документа, но по умолчанию все документы являются локальными начать (чтобы вы могли жить с хрупкой интернет-соединение).
Легкий способ переключения между вариантами документации (чтобы увидеть версии ОС), а также выберите какие комплекты документации для запуска ищет против.
В разделе "Обзор" объясняется, что класс, за которым следует раздел методы разбивки, сгруппированные по цели (методы создания и объект, методы запроса данных, методы работы с типом конверсии и т.д.), а затем подробные объяснения методов.
Мне также очень понравилась Javadoc и документация по системе Java (я использовал это в течение многих лет), я нашел преимущество в том, что было немного проще сделать ваши собственные собственные документы для ваших собственных классов, которые хорошо протекали с системой Docs. XCode позволяет также использовать Doxygen для создания документации для ваших собственных классов, но для его форматирования потребуется больше работы, а также документов системного класса, отчасти потому, что в документах системной среды больше применено форматирование.
Хороший API будет иметь следующие характеристики:
Самая распространенная ошибка, которую я вижу в дизайне API, - это то, что разработчикам кажется, что автогенерация XML-комментариев достаточно, а затем предшествовать автоматическому генерации их API на основе комментариев XML. Вот о чем я говорю:
///<summary>
/// Performs ObscureFunction to ObscureClass using ObscureArgument
///</summary>
void ObscureClass.ObscureFunction(ObscureArgument) { ... }
API, подобный приведенному выше, является только контрпродуктивным и расстраивает разработчика с использованием API. Хорошая документация API должна дать разработчикам рекомендации относительно использования API и дать им представление о некоторых аспектах API, которые они иначе не заметили бы.
Мои основные критерии - расскажите мне все, что мне нужно знать, и все, что я когда-либо захочу узнать.
QT имеет довольно приличные документы: http://doc.qt.digia.com/4.5/index.html
Win32 MSDN также довольно хорош, хотя он не успел хорошо.
Документы java ужасны для меня. Они постоянно говорят мне все, что я не хочу знать, и ничего из того, что я хочу знать. Документы .NET имеют сходную тенденцию, хотя проблема в основном заключается в чрезвычайной многословности, переполнении стольких излишних деталей и так много чертовых страниц. Почему я не могу увидеть как сводку, так и методы класса на одной странице?
Я лично считаю, что идеальным примером хорошей документации является документация PHP:
Пример: http://www.php.net/manual/en/function.fopen.php
Я думаю, что эффективная документация включает в себя:
Необязательно:
Всякий раз, когда я смотрю что-то в документации по PHP, я почти точно знаю, как использовать его, не пытаясь обыскать Интернет, чтобы найти "лучшие" примеры. Обычно единственный раз, который мне нужен для поиска в Интернете, - это когда мне нужно найти, как использовать набор функций для определенной цели. В противном случае, я думаю, что документация по PHP является лучшим примером отличной документации.
Что такое пример хорошей документации, это Python's: http://docs.python.org/py3k/library/array.html
В нем перечислены методы, но он не очень хорошо объясняет, что это такое и как его использовать. Особенно, когда вы сравниваете это с документами PHP.
Вот некоторая действительно плохая документация: Отправка отпечатка данных. Диспетчер - это библиотека Scala для HTTP, которая абстрагирует (HTTP) библиотеку Apache Commons HTTP (Java).
В нем используется много функционально-синтаксической магии, о которой не все будут очень понятны, но не дает ясного объяснения, а также решений по дизайну. Scaladocs не полезны, потому что это не традиционная библиотека в стиле Java. Чтобы действительно понять, что происходит, вам в основном нужно прочитать исходный код, и вы должны прочитать загрузки сообщений в блоге с примерами.
Документация преуспевает в том, чтобы заставить меня чувствовать себя глупо и уступать, и мне, конечно, не удается помочь мне сделать то, что мне нужно сделать. Флипсайд - это большая часть документации, которую я вижу в сообществе Ruby - как RDoc, так и в часто задаваемых вопросах/веб-сайтах/и т.д. Не просто Javadoc - вам нужно предоставить более полную документацию.
Ответьте на вопрос: "Как мне сделать X с Y?" Вы можете знать ответ. Я этого не делаю.
Мне нравится Документация по Twitter. Для меня хороший API обновлен, легко читается и содержит примеры.
Я думаю, что хороший документ API должен четко объяснить:
Не совсем документация API, но, тем не менее, весьма полезна документация базы данных Oracle, например. для инструкция SELECT. Мне нравится включение диаграмм, которые помогают прояснить использование, например.
Несколько мыслей...
Примеры - документация API win32 лучше, чем iPhone из-за:
Я проголосую за любой документ API с небольшими примерами и примерами
Никогда не показывайте "Form1", "asdf", "тестирование пользователей" в скриншотах или примерах кода
Не выполнять автообновление
Избегайте версии API API ___V2
В принципе, расскажите историю класса на уровне класса. Почему это здесь? Что делать? Что должно быть здесь? Кто написал это?
Расскажите историю методов на уровне метода. Что это делает? Независимо от того, насколько точны ваши имена методов, 20-30 символов не всегда будут вырезать его для описания.
@author:
Документация уровня интерфейса говорит мне:
Документация уровня выполнения говорит мне:
Документация по уровню уровня говорит мне:
@Deprecated сообщает мне:
Если что-то окончательно:
Если что-то статично:
В целом: вы пишете их для следующего разработчика, чтобы использовать, когда и когда вы попадаете в лотерею. Вы не хотите чувствовать себя виноватым в отказе от покупки и покупке яхты, поэтому обратите внимание на ясность и не думайте, что вы пишете для себя.
В качестве побочного преимущества, когда кто-то просит вас работать с одним и тем же кодом через два года, и вы забыли все об этом, вы в значительной степени выиграете от хорошей документации в коде.
Первая точка для большой документации API - это хорошее обозначение самого API. Имена методов и параметров должны быть указаны. Если рассматриваемый язык статически типизирован, используйте перечисления вместо String- или int-constants в качестве параметров, чтобы выбрать между ограниченным набором вариантов. Какие варианты возможны, теперь можно увидеть в типе параметра.
"мягкая часть" документации (текст, а не код) должна охватывать пограничные случаи (что произойдет, если я дам null как параметр), а документация класса должна содержать пример использования.
Хорошая документация должна иметь как минимум следующее:
Кроме того, полезно следующее:
Исходя из этого:
Примеры IMO - лучшая документация.
Мне очень нравится Документация Qt4, он сначала сталкивается с вами только с необходимой информацией, необходимой для работы, и если вы хотите копать глубже, он раскрывает все детали gory в подразделах.
То, что я действительно люблю, заключается в том, что они построили всю документацию в Qt Creator, которая предоставляет контекстно-зависимую помощь и короткие примеры, когда вам это нужно.
Одна вещь, которую я всегда хотел увидеть в документации: абзац "обоснования" для каждой функции или класса. Почему эта функция существует? Для чего он был создан? Что он обеспечивает, чего нельзя достичь каким-либо другим способом? Если ответ "ничего" (и, как это ни удивительно, часто бывает), что это за сокращение, и почему эта вещь достаточно важна, чтобы иметь свою собственную функцию?
Этот параграф должен быть легко написан - если это не так, это, вероятно, признак сомнительного интерфейса.
Недавно я встретил эту документацию (библиотека Lift JSON), которая, кажется, является хорошим примером того, что многие люди просили: хороший обзор, хороший пример, варианты использования, намерение и т.д.
Перейдите на сайт Doxygen и посмотрите примеры HTML-кода, который он генерирует. Это хорошо
Мне нравится моя документация, чтобы получить краткий обзор наверху, с полнофункциональными примерами ниже, и обсуждениями по ним! Я удивлен, что в число немногих входят простые аргументы функции с требуемыми типами переменных и значениями по умолчанию, особенно в php!
Я боюсь, что я не могу действительно привести пример, потому что я не прошел, чтобы найти, какие из них мои любимые, однако я знаю, что это, вероятно, не считается, потому что его неофициальный, но Kohana 3.0 Неофициальная вики By Kerkness просто великолепна! и Документация Kohana 2.34 неплохо выложена, ну, по крайней мере, для меня. Что вы, ребята, думаете?
Большинство людей перечислили точки, составляющие хорошую документацию API, поэтому я не буду повторять эти (спецификации типа данных, примеры и т.д.). Я просто приведу пример, который, на мой взгляд, иллюстрирует, как это должно быть сделано:
Блок приложений Unity (Перейдите в раздел "Загрузка" для CHM)
Все люди, участвующие в этом проекте, проделали большую работу по документированию этого документа и тому, как его использовать. Помимо описания API и подробного описания метода, есть много статей и образцов, которые дают вам общую картину, почему и как. Проекты с такой хорошей документацией редки, по крайней мере те, которые я использую и знаю.
Единственным критерием качества документации является то, что она ускоряет разработку. Если вам нужно знать, как что-то работает, вы идете и читаете документы. Один документ лучше другого, если вы все поняли из первого документа быстрее, чем из второго.
Любые другие качества субъективны. Стили, перекрестные ссылки, описания... Я знаю людей, которые любят читать книги. Для него будет полезен книжный документ (с содержимым/индекс/и т.д.). Другой мой друг любит документировать все внутри кода. Когда он загружает новую библиотеку, он получает источники и "читает" их вместо документов.
Я, лично, как JavaDocs. Как и Apple dev docs, за исключением частей более низкого уровня, например, Obj-C runtime (reference part) описывается ужасно. Некоторые API-интерфейсы веб-сайтов также имеют документы, которые мне нравятся.
Не нравится MSDN (это вообще хорошо, но есть слишком много вариантов одного и того же документа, я часто теряюсь).
Документация - это только часть общей картины, дизайн API. И можно утверждать, что последнее гораздо важнее, чем просто именование. Подумайте о значимых именах не дублирующих методов и т.д.
Я определенно рекомендую посмотреть презентацию Джоша Блоха об этом: http://www.infoq.com/presentations/effective-api-design ИЛИ http://www.youtube.com/watch?v=aAb7hSCtvGw
Это охватывает не только то, что вы ищете, но и многое другое.
Я нахожу API Google красивым примером хорошего API документации.
У них:
Что это! Когда я играю с сайтом документации API Google, я чувствую себя как дома.
Множество практических, реальных примеров - это необходимость. Недавним переписанием jQuery документации API является хорошим примером, а также легендарными документами Django.
Лучшая документация, которую я нашел, Python. Вы можете использовать sphinx для генерации исходной документации в HTML, LaTeX и другие, а также генерировать документы из исходных файлов; API-документ, который вы ищете.
API docs - это не только качество окончательной документации, но и то, как просто разработчики и/или технические писатели на самом деле их пишут, поэтому выберите инструмент, облегчающий работу.
Большинство упоминаний о хорошей документации уже упоминалось, но я думаю, что есть один аспект в отношении документации API-интерфейса JavaDoc, которая отсутствует: упрощение различий между сценариями использования всех классов и интерфейсов, особенно отличия между классами, которые должны использоваться клиентом библиотеки, и теми, которые не должны.
Часто JavaDoc - это почти все, что вы получаете, и обычно нет страницы документации пакета. Затем один столкнулся со списком сотен или даже более классов: где и как начать? Каковы типичные способы использования библиотеки?
Было бы хорошо, если бы были соглашения о том, как упростить предоставление этой информации в составе JavaDoc. Затем созданная документация API может допускать разные представления для разных групп людей - как минимум две группы: те, кто реализует библиотеку и тех, кто ее использует.