what tool generate from example creator api documentation

tool - web api documentation



¿Cuál considera que es una buena documentación API? (25)

Siempre me ha gustado la documentación sobre las API de Java, en términos generales, pero sé que algunas personas consideran que faltan. Entonces, me pregunto, ¿qué consideras que es un buen ejemplo de documentación API?

Por favor, incluya un enlace o un ejemplo real en cualquier respuesta. Quiero tener referencias que yo (y otros, por supuesto) podamos usar para mejorar nuestros propios documentos.

Aquí hay una documentación realmente mala: Despacho de Databinder . Dispatch es una biblioteca de Scala para HTTP que abstrae la biblioteca HTTP de Apache Commons (Java).

Utiliza una gran cantidad de magia de sintaxis funcional que no todos van a tener muy claros, pero no ofrece una explicación clara de ello, ni las decisiones de diseño que lo respaldan. Los Scaladocs no son útiles porque no es una biblioteca tradicional de estilo Java. Para entender realmente lo que está pasando, básicamente tiene que leer el código fuente y debe leer un montón de publicaciones de blog con ejemplos.

La documentación tiene éxito en hacerme sentir estúpido e inferior y ciertamente no tiene éxito en ayudarme a hacer lo que tengo que hacer. Lo contrario es la mayor parte de la documentación que veo en la comunidad de Ruby, tanto en RDoc como en las preguntas frecuentes / sitios web / etc. No solo hagas el Javadoc: necesitas proporcionar documentación más completa.

Responda la pregunta: "¿cómo hago X con Y?" Usted puede saber la respuesta. Yo no.

Básicamente, cuenta la historia de la clase a nivel de clase. ¿Por qué está aquí? ¿Qué debería hacer? ¿Qué debería estar aquí? ¿Quien lo escribió?

Cuenta la historia de los métodos en el nivel de método. ¿Qué hace esto? No importa cuán precisos sean los nombres de sus métodos, 20-30 caracteres simplemente no siempre lo recortarán por su carácter descriptivo.

@autor:

  • ¿Quién escribió esto? ¿Quién está orgulloso de eso? ¿Quién debería avergonzarse de su trabajo?

La documentación del nivel de interfaz me dice:

  • ¿Qué debería hacer esto?
  • ¿Qué devolverá?

La documentación del nivel de implementación me dice:

  • ¿cómo lo hace? qué tipo de algoritmo? ¿Qué tipo de carga del sistema?
  • ¿Qué condiciones pueden causar un problema? ¿La entrada nula causará un problema? son números negativos, ¿está bien?

La documentación de nivel de clase me dice:

  • ¿Qué pasa aquí? ¿Qué tipo de métodos debo esperar encontrar?
  • ¿Qué representa esta clase?

@Deprecated me dice:

  • ¿Por qué se planea su eliminación?
  • ¿Cuándo se espera que se elimine?
  • ¿Cuál es el reemplazo sugerido?

Si algo es final:

  • ¿Por qué no quieres que extienda esto?

Si algo es estático:

  • recuérdame en el documento de nivel de clase, al menos implícitamente.

En general: estás escribiendo esto para el próximo desarrollador que use si y cuando llegas a la lotería. No quiere sentirse culpable por dejar de fumar y comprar un yate, así que preste un poco de atención a la claridad y no suponga que está escribiendo para usted.

Como beneficio adicional, cuando alguien le pida que trabaje con el mismo código dentro de dos años y lo haya olvidado por completo, se beneficiará enormemente de la buena documentación en código.

Considero que las API de Google son un bello ejemplo de API de buena documentación.

Ellos tienen:

  1. Vista de pájaro de toda la estructura de las API
  2. Resumen de las características principales de la API única
  3. Ejemplos agradables y coloreados para una respuesta rápida
  4. Referencias detalladas
  5. Un blog que te mantiene actualizado
  6. Un grupo de google que documenta problemas y soluciones
  7. Videos
  8. Preguntas más frecuentes
  9. Artículos
  10. Presentaciones
  11. Code Playground
  12. Un motor de búsqueda para gatear dentro de una pila de documentación

¡Eso es! Cuando juego con el sitio de documentación de las API de google, me siento como en casa.

Creo que un buen documento de API debe explicar claramente:

  1. Qué problema soluciona esta API
  2. Cuando deberías usarlo
  3. Cuando no deberías usarlo
  4. Código real que muestra el uso de "mejores prácticas" de la API

No es exactamente la documentación de la API pero, sin embargo, bastante útil es la documentación de la base de datos Oracle, por ejemplo, para la instrucción SELECT . Me gusta la inclusión de diagramas que ayudan a aclarar el uso, por ejemplo.

El único criterio para la calidad de la documentación es que acelera el desarrollo. Si necesita saber cómo funciona algo, vaya y lea documentos. Un documento es mejor que otro si ha entendido todo desde el primer documento más rápido que desde el segundo.

Cualquier otra cualidad es subjetiva. Estilos, referencias cruzadas, descripciones ... Conozco personas a las que les gusta leer libros. El documento con estilo de libro (con contenido / índice / etc.) será bueno para él. Otro mi amigo le gusta doc todo dentro del código. Cuando descarga una nueva biblioteca, obtiene fuentes y las "lee" en lugar de documentos.

Yo, personalmente, me gusta JavaDocs. Al igual que los documentos de desarrollo de Apple, con la excepción de las partes de nivel inferior, por ejemplo, el tiempo de ejecución Obj-C (parte de referencia) se describe terriblemente. Varias API de sitios web también tienen documentos que me gustan.

No me gusta MSDN (es bueno en general, pero hay demasiadas variantes del mismo documento, me pierdo a menudo).

El primer punto para una excelente documentación de la API es una buena denominación de la misma API. Los nombres de los métodos y parámetros deberían ser decir todo. Si el idioma en cuestión está tipado estáticamente, use enumeraciones en lugar de constantes String o int como parámetros, para seleccionar entre un conjunto limitado de opciones. Las opciones posibles ahora se pueden ver en el tipo de parámetro.

La ''parte blanda'' de la documentación (texto, no código) debe cubrir los casos límite (lo que sucede si doy nulo como parámetro) y la documentación de la clase debe contener un ejemplo de uso.

En realidad, la documentación de iPhone (realmente Mac Cocoa / framework) se ha vuelto bastante buena. Las características que me gustan son:

  • Muy fácil saltar a los documentos de la API.

  • Bien formateado y los fragmentos de código que desea copiar y pegar (como las firmas de métodos) se destacan.

  • Enlaces a proyectos con código de muestra directamente desde los documentos.

  • Mecanismo automatizado de actualización de documentos, pero los documentos predeterminados son todos locales para comenzar (para que pueda vivir con una conexión a Internet escamosa).

  • Una manera fácil de cambiar entre las variantes de la documentación (para ver las diferentes versiones del sistema operativo), y también seleccionar los conjuntos de documentación para ejecutar búsquedas en contra.

  • Una sección de descripción general explica para qué es la clase, seguida de una sección que desglosa los métodos agrupados por propósito (métodos para crear y objetar, métodos para consultar datos, métodos para trabajar con conversiones de tipo, etc.), seguidos de las explicaciones detalladas del método.

También me gustó mucho Javadoc y la documentación del sistema Java (lo usé durante muchos años), encontré una ventaja: era un poco más fácil crear tus propios documentos personalizados para tus propias clases que fluían bien con los documentos del sistema. XCode también le permite usar Doxygen para generar documentación para sus propias clases, pero se necesitaría más trabajo para formatearlo, así como también los documentos de la clase del sistema, en parte porque los documentos de la estructura del sistema tienen más formato aplicado.

La mayoría de las cosas sobre buena documentación ya se mencionaron, pero creo que falta un aspecto sobre la forma de JavaDoc de la documentación de la API: hacer que sea fácil distinguir entre los escenarios de uso de todas las diferentes clases e interfaces, especialmente distinguir entre clases que debe ser utilizado por un cliente de biblioteca y aquellos que no deberían.

A menudo, JavaDoc es casi todo lo que obtienes y generalmente no hay una página de documentación del paquete. Uno se enfrenta a una lista de cientos o incluso más de clases: ¿dónde y cómo comenzar? ¿Cuáles son las formas típicas de usar la biblioteca?

Sería bueno si hubiera convenciones de cómo facilitar la entrega de esta información como parte de JavaDoc. Luego, la documentación de la API generada podría permitir diferentes vistas para diferentes grupos de personas, como mínimo dos grupos: los que implementan la biblioteca y quienes la usan.

La mayoría de las personas ha enumerado los puntos que conforman una buena documentación de la API, por lo que no voy a repetirlos (especificaciones de tipo de datos, ejemplos, etc.). Solo voy a dar un ejemplo que creo que ilustra cómo debería hacerse:

Bloque de aplicaciones de Unity (Vaya a la sección de descargas para el CHM)

Todas las personas involucradas en este proyecto han hecho un gran trabajo al documentarlo y cómo se debe usar. Además de la referencia de API y la descripción detallada del método, hay muchos artículos y muestras que le dan una idea general, el por qué y el cómo. Los proyectos con tan buena documentación son raros, al menos los que uso y conozco.

La mejor documentación que he encontrado es Python . Puede usar sphinx para generar la documentación fuente en HTML, LaTeX y otros, y también generar documentos desde archivos fuente; el API doc que está buscando.

API docs no es solo la calidad de la documentación final, sino también lo fácil que es para los desarrolladores y / o escritores técnicos escribirla, así que elija una herramienta que facilite el trabajo.

Los ejemplos de IMO son la mejor documentación.

Me gusta mucho la Documentación Qt4 , primero te confronta solo con la información esencial que necesitas para que las cosas funcionen, y si quieres profundizar, revela todos los detalles sangrientos en las subsecciones.

Lo que realmente amo, es el hecho de que crearon toda la documentación en Qt Creator, que brinda ayuda contextual y ejemplos breves cuando los necesita.

Me gusta que mi documentación tenga una breve descripción general en la parte superior, con ejemplos completos a continuación, y discusiones debajo de estos. Me sorprende que pocos incluyan argumentos de funciones simples con sus tipos de variables requeridos y valores predeterminados, ¡especialmente en php!

Me temo que realmente no puedo dar un ejemplo porque no he navegado para encontrar cuál es mi favorito, sin embargo, sé que esto probablemente no cuenta porque no es oficial, pero Wiki no oficial de Kohana 3.0 ¡Por Kerkness es simplemente brillante! y la documentación de Kohana 2.34 también está muy bien diseñada, al menos para mí. ¿Qué piensan ustedes?

Mi criterio principal es: dime todo lo que necesito saber y todo lo que siempre desearía saber.

QT tiene documentos bastante decentes: http://doc.qt.digia.com/4.5/index.html

Win32 MSDN también es bastante bueno, aunque no envejeció bien.

Los documentos de Java son horribles para mí. Constantemente me dicen todo lo que no quiero saber y nada de lo que quiero saber. Los documentos .NET tienen una tendencia similar, aunque el problema allí es principalmente la extrema palabrería, el desbordamiento de tantos detalles superfluos y tantas malditas páginas. ¿Por qué no puedo ver tanto el resumen como los métodos de una clase en la misma página?

Muchos ejemplos prácticos del mundo real son obligatorios. La reciente reescritura de la documentación API de jQuery es un buen ejemplo, así como los documentos legendarios de Django.

Personalmente, creo que un ejemplo perfecto de buena documentación es la documentación de PHP:

Para un ejemplo: http://www.php.net/manual/en/function.fopen.php

Creo que la documentación efectiva incluye:

  • Listado de parámetros
  • (Útil) descripción del parámetro
  • Si los parámetros son una cadena, enumere y EXPLIQUE cada posible parámetro posible
  • Devuelve valores tanto en la ejecución exitosa como en la ejecución no exitosa
  • Cualquier excepción / error que pueda generar
  • Ejemplos (LO MÁS IMPORTANTE)

Opcionalmente:

  • Registro de cambios
  • Notas / Ejemplos de otros usuarios

Cada vez que busco algo en la documentación de PHP, casi sé exactamente cómo usarlo sin tener que buscar en internet para encontrar ejemplos "mejores". Por lo general, el único momento que necesito para buscar en Internet es cuando necesito encontrar cómo usar un conjunto de funciones para un propósito específico. De lo contrario, creo que la documentación de PHP es el mejor ejemplo de documentación excelente.

Lo que es pensar es un ejemplo de una buena documentación es Python: http://docs.python.org/py3k/library/array.html

Enumera los métodos pero no hace un buen trabajo al explicar en profundidad qué es y cómo usarlo. Especialmente cuando lo comparas con los documentos de PHP.

Recientemente me he encontrado con this documentación (la biblioteca de Lift JSON), que parece ser un buen ejemplo de lo que muchas personas han pedido: buena visión general, buen ejemplo, casos de uso, intención, etc.

Solo algunos pensamientos ...

  1. Ejemplos: la documentación de la API de win32 es mejor que la de iPhone debido a:

    • ejemplos de código (corto)

    Voto por cualquier documento API con ejemplos pequeños y con sentido

  2. Nunca muestres nunca "Form1", "asdf", "probar usuarios" en capturas de pantalla o códigos de muestra

    • una buena API soluciona problemas del mundo real y debería haber algunos ejemplos significativos

  3. Do not auto-gen doc

    • la documentación no debe hacerse durante la escritura del código (o por el mismo tipo)
    • doc es para un extraño, a quien los programadores generalmente no les importa

  4. Evita la versión ___V2 de la API

    • pero no es un problema de doc

Una buena API tendrá las siguientes características:

  • Fácil de aprender
  • Fácil de usar, incluso sin documentación
  • Difícil de usar mal
  • Fácil de leer y mantener el código que lo usa
  • Suficientemente poderoso para satisfacer los requisitos
  • Fácil de extender
  • Apropiado para la audiencia

El error más común que veo en el diseño de la API es cuando los desarrolladores sienten que los comentarios XML generados automáticamente son suficientes y luego preceden para generar automáticamente su API en función de los comentarios XML. Esto es de lo que estoy hablando:

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

Las API como la anterior son solo contraproducentes y frustran al desarrollador que usa la API. Una buena documentación de la API debería dar a los desarrolladores consejos sobre cómo usar la API y darles una idea de ciertas facetas de la API que de otra manera no notarían.

Una buena documentación DEBE tener:

  • especificaciones de tipos de datos, a menudo más esenciales que las funciones reales. NO trates esto a la ligera.
  • especificaciones de función (esto es obvio). Incluyendo qué función dada tiene, por qué lo hace (si no es obvio), y advertencias si las hay.
  • un documento introductorio que vincula el todo en una entidad lógica, explicando las intenciones, los patrones de uso correctos y las ideas más allá del alcance del código API real. Normalmente se le asignan 50 funciones diferentes y no se sabe cuál debe usarse, lo que no debe usarse fuera de casos específicos, que se recomiendan para alternativas más oscuras y por qué deben usarse de esa manera.
  • ejemplos. A veces son más importantes que todo el resto

Sé cómo dibujar una forma arbitraria de color arbitrario en GTK +. Todavía no tengo idea de por qué un cambio en el color del dibujo requiere tres líneas bastante largas de líneas de código muy oscuras y poco intuitivas. Recordando el setcolorRGB(r,g,b); draw(x1,y1,x2,y2); de SVGAlib setcolorRGB(r,g,b); draw(x1,y1,x2,y2); setcolorRGB(r,g,b); draw(x1,y1,x2,y2); Me resulta realmente difícil comprender lo que poseían los autores de GTK + para complicar tanto las cosas. Tal vez si explicaran los conceptos subyacentes en lugar de simplemente documentar las funciones que los usan, lo entendería ...

Otro ejemplo: ayer recibí una respuesta que me permitió entender SQLite. Entendí una función de extracción de datos de una columna devuelta signed long long . Entendí que las columnas enteras podrían tener 1,2,4,6 y 8 bytes de longitud. Entendí que puedo definir una columna como "UNSIGNED INT8" o "TINYINT". No entendí exactamente lo que significaba "afinidad", solo sabía que ambos tenían afinidad "INTEGER". Pasé horas buscando si las marcas de tiempo deberían ser UNSIGNED INTEGER o INT8, si INT8 tiene 8 dígitos u 8 bytes, y cuál es el nombre de esa int esotérica de 6 bytes.

Lo que extrañé fue que "UNSIGNED INT8", "TINYINT" y similares son todos sinónimos sintácticos de azúcar para el tipo "INTEGER" (que siempre está signed long long ), y las longitudes dadas son para el almacenamiento interno solamente, se ajustan automáticamente y de forma transparente para adaptarse a cualquier valor en el menor número de bits y son totalmente invisibles e inaccesibles desde el lado de la API.

Una buena documentación debe tener al menos lo siguiente:

  • Cuando un argumento tiene limitaciones adicionales más allá de su tipo, deben estar completamente especificadas.
  • Descripción del estado [requerido] de un objeto antes de llamar al método.
  • Descripción del estado de un objeto después de llamar al método.
  • Descripción completa de la información de error proporcionada por el método (valores de retorno, posibles excepciones). Simplemente nombrarlos es inaceptable .
    • Buen ejemplo : lanza ArgumentOutOfRangeException si el índice es menor que 0 o el índice es mayor o igual que Count.
    • Ejemplo incorrecto: devuelve 0 para el éxito o uno de los siguientes E_INVALIDARG, etc ... (sin especificar qué hace que un argumento sea inválido). Este es el enfoque estándar de "desarrollador de FU" tomado en el PS3 SDK.

Además, los siguientes son útiles:

  • Descripción del estado de un objeto si el método arroja una excepción.
  • Mejores prácticas con respecto a clases y grupos de clases (por ejemplo, exceptions en .NET) en la API.
  • Ejemplo de uso

Basado en esto:

  • Un ejemplo de gran documentación es la biblioteca de MSDN.
    • Para ser justos, la versión en línea de esto tiene una dificultad de navegación en los casos.
  • Un ejemplo de documentación terrible es el PS3 SDK. Aprender una API requiere una extensa prueba de los argumentos del método para adivinar cuáles pueden ser o no los requisitos reales y el comportamiento de cualquier método dado.

Una cosa que siempre quise ver en la documentación: un párrafo de "justificación" para cada función o clase. ¿Por qué esta función está ahí? ¿Para qué fue construido? ¿Qué proporciona eso que no se puede lograr de ninguna otra manera? Si la respuesta es "nada" (y sorprendentemente con frecuencia lo es), ¿qué es una abreviación, y por qué es eso lo suficientemente importante como para tener su propia función?

Este párrafo debería ser fácil de escribir; si no lo es, probablemente sea una señal de una interfaz dudosa.