Que considérez-vous comme une bonne documentation API?

Question

J'ai toujours aimé la documentation sur les API Java, en général, mais je sais que certaines personnes les considèrent comme manquantes. Je me demande donc quel est, selon vous, un bon exemple de documentation sur les API?

Veuillez inclure un lien ou un exemple concret dans une réponse. Je veux avoir des références que moi (et d'autres, bien sûr) pouvons utiliser pour améliorer nos propres documents.

Answer 1

Une bonne documentation DOIT avoir:

• les types de données specs - souvent plus essentiel que les fonctions réelles. Ne PAS traiter à la légère.
• fonction spécifications (c'est évident). Y compris Ce que la fonction fait, pourquoi il le fait (pas si évident), et les mises en garde, le cas échéant.
• un document qui lie le tout en une entité logique, en expliquant les intentions, l'utilisation correcte des modèles et des idées au-delà de la portée effective de code de l'API. Normalement, vous êtes donné 50 fonctions différentes et vous ne savez pas qui doit être utilisé, ce qui ne doit pas être utilisé en dehors de cas particuliers, qui sont recommandés pour les plus obscures des solutions de rechange et pourquoi doivent-ils être utilisés de cette façon.
• des exemples. Parfois, ils sont plus importants que tout le reste

Je sais comment dessiner une forme arbitraire de l'arbitraire de la couleur dans GTK+. Je n'ai toujours aucune idée pourquoi un changement de couleur de tracé nécessite trois très longues lignes de très sombre, assez peu intuitive de lignes de code. Se souvenir de SVGAlib setcolorRGB(r,g,b); draw(x1,y1,x2,y2); je trouve ça vraiment difficile de comprendre ce qui poussa les auteurs de GTK+ pour compliquer les choses à ce point. Peut-être que si ils ont expliqué les concepts sous-jacents au lieu de simplement documenter les fonctions qui les utilisent, je comprendrais...

Un autre exemple: hier, j'ai eu une réponse qui m'a permis de comprendre SQLite. J'ai compris une fonction d'extraction de données à partir d'une colonne renvoie signed long long. J'ai compris les colonnes de type entier pourrait être 1,2,4,6 et 8 octets de long. J'ai compris que je peux définir une colonne "UNSIGNED INT8", ou "de type TINYINT". Je n'ai pas très bien ce que "affinité" voulait dire, je savais juste que les deux avaient des "INTEGER" affinité. J'ai passé des heures à chercher si les horodatages doit être ENTIER non signé ou INT8, si INT8 est de 8 chiffres ou 8 octets, et quel est le nom de cette ésotérique de 6 octets int?

Ce que j'ai remarqué, c'est que "UNSIGNED INT8", "TINYINT" et les autres sont tous un sucre syntaxique synonymes de type "ENTIER" (qui est toujours signed long long), et les longueurs indiquées sont pour le stockage de disque interne seulement, sont ajustés automatiquement et de manière transparente pour l'adapter à toute valeur sur moins de bits et sont totalement invisibles et inaccessibles à partir de l'API de côté.

Answer 2

En fait l'iPhone (vraiment Mac Cacao/cadre) de la documentation a reçu assez bonne. Les fonctionnalités que j'aime sont:

• Très facile de sauter à la documentation de l'API.

• Bien formatés et les extraits de code vous voulez copier et coller (comme les signatures de méthode).

• Liens vers des projets avec des exemples de code droit de la documentation.

• Automatique de document mécanisme d'actualisation, mais par défaut, les docs sont tous les locaux à le début (de sorte que vous pouvez vivre avec une pâte feuilletée connexion internet).

• Moyen facile de passer entre les variantes de la documentation (voir les différentes les versions de l'OS), et également sélectionner qui jeux de documents pour exécuter les recherches contre.

• Une vue d'ensemble section explique ce que l' classe, suivie par une section briser les méthodes regroupées par but (méthodes pour créer et objet, méthodes de requête pour les données, méthodes de travail avec ce type de les conversions, etc), suivie par la méthode détaillée des explications.

J'ai aussi personnellement vraiment aimé Javadoc et la Java de la documentation du système (que j'ai utilisé pendant de nombreuses années), j'ai trouvé un avantage était qu'elle était un peu plus facile de faire vos propres docs pour vos propres classes qui coulait bien avec le système docs. XCode permet également d'utiliser Doxygen pour générer la documentation pour vos propres classes, mais il en faudrait un, mais plus de travail pour le format ainsi que le système de classe docs, en partie parce que le système de documents-cadres ont plus la mise en forme appliquée.

Answer 3

Une bonne API devra avoir les caractéristiques suivantes:

• Facile à apprendre
• Facile à utiliser, même sans documentation
• Difficile de mauvaise utilisation
• Facile à lire et à maintenir le code qui l'utilise
• Suffisamment puissant pour satisfaire les exigences de
• Facile à étendre
• Approprié à l'auditoire.

L'erreur la plus commune que je vois dans la conception d'API, c'est quand les développeurs se sentent auto-généré des commentaires XML est suffisant, et puis précéder à l'auto-produire leur API basé sur les commentaires XML. Voici de quoi je parle:

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

Les API comme celle ci-dessus sont seulement contre-productif, et de contrecarrer les développeurs utilisant l'API. Bonne documentation de l'API devrait donner aux développeurs des indications sur comment utiliser l'API et de leur donner un aperçu de certaines facettes de l'API autrement ils n'auraient pas remarqué.

Answer 4

Ici est vraiment de mauvaise documentation: Databinder Expédition. L'expédition est un Scala bibliothèque pour HTTP que l'abstraction de l' (Java) Apache Commons HTTP bibliothèque.

Il utilise beaucoup de fonctionnelle de la syntaxe de magie que le monde n'est pas très clair, mais ne fournit aucune explication quant à elle, ni les décisions de conception derrière elle. Le Scaladocs ne sont pas utiles, car il n'est pas un Java traditionnelle de style de la bibliothèque. Pour vraiment comprendre ce qui se passe, vous avez essentiellement pour lire le code source et vous devez lire un chargement de messages de blog avec des exemples.

La documentation réussit à me faire sentir stupide et inférieurs, et il n'est certainement pas réussir à m'aider à faire ce que je dois faire. Le revers de la médaille est que la plupart de la documentation, je vois dans la communauté Ruby - deux RDoc et dans Faq/sites web/etc. Ne vous contentez pas de faire la Javadoc - vous besoin de fournir une documentation plus complète.

Répondre à la question: "comment dois-je faire X avec Y?" Vous savez peut-être la réponse. Je n'ai pas.

Answer 5

Mon critère principal est - dites-moi tout ce que j'ai besoin de savoir et de tout ce dont je pourrais avoir envie de savoir.

QT a pas mal de docs: http://doc.trolltech.com/4.5/index.html

Win32 MSDN est également assez bonne, bien qu'elle n'a pas d'âge.

La java docs sont horrible pour moi. Ils ne cessent de me dire tout ce que je ne veux pas le savoir, et rien de ce que je veux savoir. L' .NET docs a une tendance similaire, bien que le problème, c'est surtout l'extrême wordyness, de dépassement de tant de détails superflus et tellement god damn pages. Pourquoi ne puis-je pas voir à la fois le résumé et les méthodes d'une classe dans la même page?