Наиболее интуитивно понятная справочная документация по API / языку

Question

Я работаю над ужасным последним этапом проекта: документирование API для полутехнической аудитории.

Мне интересно: какие документы по API вы считаете особенно элегантными?

Обратите внимание, что не имеет никакого отношения к тому, насколько элегантен сам API: это просто вопрос форматирования / внешнего вида самих документов API. Какой язык или документы API передают информацию наиболее понятным и понятным способом?

Answer 1

Мне всегда нравились javadocs и руководства для стандартной библиотеки Java .

Answer 2

Мне нужно пойти с MSDN Library . Они отлично справляются с документированием условий до и после процедуры и превосходной согласованностью с огромным набором API.

Answer 3

Джанго.

Answer 4

Python имеет очень компактную, но удивительно понятную документацию:

http://docs.python.org/index.html

Answer 5

Flex ... Я действительно нахожу этот вид настройки идеальным.

Answer 6

Два от макушки моей головы:

• Zend Framework
• Python (использует Sphinx)

Answer 7

Документация Python - моя любимая.

Answer 8

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

Возможно, это просто случай жить в основном на земле Microsoft, но я никогда не видел язык документации API, который я могу читать так же легко, как и код.

Два источника документации, которые я регулярно читаю, - это электронная документация по SQL Server и документация MSDN C #. Я абсолютно ненавижу языки технической документации, используемые на обоих. Я нахожу, что почти 100% времени я погружаюсь прямо к примерам кода.

Например, ниже несколько строк из ссылки на t-sql для select - я пишу операторы select каждый день, но с этим действительно борюсь:

SELECT statement ::= 
    < query_expression > 
    [ ORDER BY { order_by_expression | column_position [ ASC | DESC ] } 
        [ ,...n ]    ] 
    [ COMPUTE 
        { { AVG | COUNT | MAX | MIN | SUM } ( expression ) } [ ,...n ] 
        [ BY expression [ ,...n ] ] 
    ] 
    [ FOR { BROWSE | XML { RAW | AUTO | EXPLICIT } 
            [ , XMLDATA ] 
            [ , ELEMENTS ]
            [ , BINARY base64 ]
        } 
] 

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

---

РЕДАКТИРОВАТЬ - я чувствовал необходимость быть немного позитивным в отношении MSDN, я использую его чаще всего каждый день и нахожу его большим количеством информации, но обычно это примеры кода и пояснительный текст, а не API документация, которая дает мне информацию, которая мне нужна.