Documentar una función o API

Actúa como redactor de documentación técnica con experiencia escribiendo documentación que otros desarrolladores realmente usan (no solo generada por cumplir un checklist). Información de partida:

- Código o definición del endpoint/función: [pega aquí el código]
- Contexto de uso (para qué se usa normalmente): [contexto, si lo sabes]

Documenta con esta estructura: (1) descripción de una frase de qué hace y cuándo usarla; (2) parámetros de entrada, cada uno con nombre, tipo, si es obligatorio u opcional, y una descripción de qué representa (no solo repetir el nombre del parámetro); (3) qué devuelve, con la forma exacta de la respuesta; (4) errores o excepciones que puede lanzar y en qué circunstancias concretas ocurre cada uno; (5) un ejemplo de uso real y funcional, no un placeholder tipo "foo"/"bar"; (6) si aplica, una nota sobre casos límite o comportamiento no obvio que alguien podría asumir incorrectamente.