Guía de estilo para referencias de API: una misma estructura para cada entrada

Qué es

Una entrada de referencia describe una función, un endpoint, un tipo o una opción. Una guía de estilo para material de referencia es un documento interno breve que fija, para todas las entradas, las secciones y su orden, la forma de la frase inicial y la redacción de los datos recurrentes. La guía de referencia de Microsoft (citada) enumera las secciones de un artículo de referencia en un orden fijo: título y descripción, declaración o sintaxis, parámetros, valor de retorno, observaciones, ejemplo, requisitos y véase también, con excepciones o códigos de error cuando el elemento puede producirlos. Cada parámetro indica su tipo de datos y, cuando procede, si es obligatorio u opcional, y la descripción no debe limitarse a repetir el nombre del elemento. La guía de Google para comentarios de referencia de API (citada) señala que solo la primera frase de una descripción aparece en las secciones de resumen y en los índices, por lo que la información más importante debe ir ahí, y que una deprecación debe indicar qué usar en su lugar. OpenAPI (citado) distingue entre summary, una declaración breve de lo que hace una operación, y description, más extensa.

Por qué importa

El material de referencia se lee por consulta, no de principio a fin. Quien ha aprendido dónde está el valor de retorno en una entrada espera encontrarlo en el mismo lugar en la siguiente; un agente que extrae parámetros depende de esa misma regularidad. Las referencias generadas (a partir de docstrings, OpenAPI o comentarios de documentación) reproducen la disciplina que tenga la fuente, de modo que la guía de estilo se aplica en el origen.

Cómo aplicarlo

• Primera frase: una declaración completa de lo que hace el elemento, en tercera persona y que empiece con un verbo («Devuelve el ...», «Crea un ...»), que tenga sentido por sí sola en un índice.
• Parámetros: nombre, tipo, obligatorio u opcional, valor por defecto, rango o formato permitido y qué ocurre en el límite. Un parámetro sin valor por defecto indicado tiene un comportamiento sin documentar.
• Valor de retorno: tipo, significado y los casos de vacío, nulo o no encontrado.
• Errores: una línea por condición, con la forma «condición: error lanzado o estado devuelto»; enlace al formato de error compartido.
• Observaciones: garantías de orden, idempotencia, efectos secundarios, límites de tasa, seguridad en hilos. Nada que corresponda a un tutorial.
• Ejemplo: una única llamada mínima y ejecutable con su salida; siempre que sea posible, conviene ejecutarlo en CI.
• Deprecación: el reemplazo, la versión a partir de la cual está obsoleto y el plan de eliminación, en la primera frase.
• Terminología: usar el término preferido del glosario para cada concepto y las mismas unidades y formatos de fecha en todo el material.

Trampas

Resúmenes que repiten el nombre («getUser: obtiene el usuario»). Describir la implementación en lugar del contrato. Restricciones expresadas solo en prosa que un validador aplica de otra manera. Ejemplos que ya no se ejecutan. Órdenes de secciones distintos según el autor, que es justo el problema que la guía existe para eliminar.