Documentar su código
El código sin documentar es un impuesto que todo equipo paga dos veces: la primera cuando el autor original olvida qué escribió, y la segunda cuando la siguiente persona contratada tiene que hacer ingeniería inversa. Este endpoint lee su código fuente y genera docstrings, descripciones de parámetros y documentación de referencia lista para subir al repositorio.
Ejecútela online
Ejecute esto en nuestros servidores con su cuenta. Las herramientas gratuitas corren en su navegador; esta cobra de su saldo del KIT según el precio de arriba.
Quién termina necesitando esto
El caso típico es un equipo que heredó un servicio con cien funciones públicas y cero comentarios, o una persona que mantiene un proyecto sola, escribe rápido y nunca documenta. También aparece en pipelines de integración continua que bloquean un merge si alguna función exportada nueva no trae docstring, y en librerías que preparan su primer lanzamiento público donde el código funciona pero nadie sabría cómo usarlo desde afuera.
Qué envía y qué recibe
Envía un archivo fuente o un bloque de funciones, indicando opcionalmente el lenguaje y la convención de docstring deseada (estilo Google, estilo NumPy, JSDoc, PHPDoc y similares se infieren del código si no la especifica). La tarea devuelve el mismo código con docstrings insertados sobre cada función, más un bloque de referencia por símbolo: nombre, parámetros con tipos inferidos, valor de retorno y una descripción en lenguaje llano de lo que la función realmente hace, no solo su firma repetida.
Por qué importa el formato elegido
Las convenciones de docstring existen porque hay herramientas que las leen: Sphinx, JSDoc, Doxygen y los tooltips del editor parsean una forma de comentario específica para generar ayuda emergente y sitios de documentación. Un docstring bien escrito pero en el formato equivocado es invisible para su proceso de documentación, así que la API pide o infiere la convención correcta en lugar de asumir una genérica y dejarle reformatear quinientas funciones a mano.
Dónde encaja en su flujo de trabajo
Como cada llamada es asíncrona, el lugar natural para esto es un hook previo al merge o un job programado que compare el último commit documentado contra el HEAD y solo envíe las funciones nuevas o modificadas. El webhook firmado deposita el código anotado de vuelta en su sistema de build sin que nadie abra el archivo, y el enlace firmado con validez de 24 horas cubre las corridas manuales donde alguien simplemente quiere pegar un archivo y recibirlo de vuelta.
Lo que no hace
Documenta lo que el código hace y cómo se invoca, basándose en la lógica presente; no inventa comportamiento, no adivina intención de negocio que no esté expresada en el código, ni fabrica ejemplos que no puedan derivarse del cuerpo de la función. Si una función es genuinamente ambigua, la descripción lo indica en vez de inventar algo.
Qué puede hacer con ella
Entrega de un servicio heredado
Un equipo que recibe una API interna de cinco años de antigüedad procesa cada archivo de controladores por el endpoint para obtener docstrings base antes de tocar la lógica.
Pulido previo a una versión pública
Quien mantiene un proyecto de código abierto documenta la superficie pública del paquete la semana antes de etiquetar la versión 1.0, para que quienes lo adopten temprano tengan documentación real de parámetros en vez de leer el fuente.
Control de documentación en integración continua
Un paso del pipeline envía solo las funciones modificadas en un pull request y hace fallar la revisión si los docstrings devueltos señalan un parámetro sin propósito discernible.
Referencia de API entre equipos
Un equipo de plataforma genera documentación de referencia para funciones de un SDK interno, para que otras áreas puedan integrarse sin preguntar por chat cada vez.
Preguntas frecuentes
¿Qué lenguajes soporta la API de documentación de código?
Soporta lenguajes habituales como JavaScript, TypeScript, Python, PHP, Java, Go y C#; la convención de docstring se infiere del lenguaje salvo que especifique una.
¿Hay un plan gratuito para probarla?
No hay capa gratuita: las capas gratis se abusan y ralentizan a todos. El acceso funciona con un saldo prepago de ForHosting KIT: se recarga desde $10.00 (no caduca) y cada solicitud se cobra a su precio publicado, así que una llamada sin saldo devuelve HTTP 402. Sin suscripción, sin tokens ni créditos inventados, y una tarea fallida no se cobra.
¿Cómo se cobra la solicitud?
$0.003 por solicitud más $0.0135 por cada 1000 palabras de fuente procesadas, y solo se cobran las tareas que se completan con éxito.
¿Qué pasa si la tarea falla?
Se reintenta automáticamente hasta tres veces; si sigue fallando recibe un error claro y nunca se le cobra esa solicitud.
¿Puedo enviar un archivo completo en vez de una sola función?
Sí, puede enviar un archivo completo y la API documenta cada función exportada o método de clase que encuentre, devolviéndolos en línea o como bloque de referencia aparte.
¿Cómo recibo el resultado?
Por webhook firmado hacia su endpoint, recomendado para pipelines automatizados, o por enlace firmado con validez de 24 horas para corridas manuales o puntuales.
¿Elige el estilo de docstring por mí?
Infiere una convención razonable según el lenguaje y el estilo existente del código, o puede forzar una explícitamente, como Python estilo Google o JSDoc.
¿Se conserva mi código fuente después?
No. El código enviado y la documentación generada se eliminan al vencer el período de retención y nunca se usan para entrenamiento.
Para desarrolladores — acceso por API
Todo lo de esta página está disponible por programación. Esta sección es para equipos que quieren integrarlo en sus sistemas; el resto puede usar la herramienta de arriba sin más.
Endpoint de API
¿Prefiere automatizarlo? Un POST autenticado crea la tarea; el resultado llega por webhook o enlace firmado. La misma capacidad también se ejecuta aquí en la web, y pronto desde nuestra app, el email y Telegram.
Llámela desde su stack
curl -X POST https://api.kit.forhosting.com/dev/code-document \
-H "Authorization: Bearer $KIT_KEY" \
-H "Content-Type: application/json" \
-d '{"text":"…"}'const res = await fetch("https://api.kit.forhosting.com/dev/code-document", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.KIT_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
"text": "…"
})
});
const { task_id } = await res.json();import os, requests
res = requests.post(
"https://api.kit.forhosting.com/dev/code-document",
headers={"Authorization": f"Bearer {os.environ['KIT_KEY']}"},
json={
"text": "…"
},
)
task_id = res.json()["task_id"]<?php
$res = file_get_contents("https://api.kit.forhosting.com/dev/code-document", false, stream_context_create([
"http" => [
"method" => "POST",
"header" => "Authorization: Bearer " . getenv("KIT_KEY") . "\r\nContent-Type: application/json",
"content" => '{"text":"…"}',
],
]));
$task = json_decode($res, true);body := bytes.NewBufferString(`{"text":"…"}`)
req, _ := http.NewRequest("POST", "https://api.kit.forhosting.com/dev/code-document", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("KIT_KEY"))
req.Header.Set("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)Ejemplo de solicitud
{
"text": "…"
}Ejemplo de respuesta
{
"task_id": "tsk_a1b2c3d4e5f6a1b2c3d4e5f6",
"type": "dev.code_document",
"status": "queued",
"_links": {
"result": "/tasks/tsk_…/result"
}
}La API es asíncrona: la llamada devuelve un task_id al instante y el resultado llega por webhook. El polling está limitado a 1 req/s por tarea.
Precio
Precio publicado — sin tokens ni créditos inventados. Una tarea fallida no se cobra.
Errores
| HTTP | Código | Significado |
|---|---|---|
401 | unauthorized | API key ausente o inválida. |
402 | insufficient_balance | El saldo no cubre el precio de la tarea. |
404 | unknown_type | El tipo de tarea no existe. |
429 | rate_limited | Demasiadas peticiones. Use el webhook en vez de sondear. |
422 | task_failed | La tarea falló tras 3 reintentos. No se cobra. |