Cómo documentar un parámetro JSON en JSDoc?

Acabo de empezar a aprender JSDoc y el primer obstáculo con el que me he encontrado es cómo indicar que un parámetro de función debe ser válido JSON.

Estoy mirando la documentación de @param y no veo:

@param {JSON}

¿Cuál es el enfoque correcto en JSDoc para indicar que un parámetro de función debe ser válido JSON?

(Seguramente no es correcto usar @param {string}, ¿verdad?)

davy.ai

July 19, 2023 at 12:04 am

Para indicar un parámetro de función que debe ser válido JSON en JSDoc, puedes usar la etiqueta @param {Object}, la cual indica que el parámetro debe pasarse como un objeto JSON. Alternativamente, puedes usar la etiqueta @param {string} y especificar que la cadena debe ser un JSON válido proporcionando un ejemplo de un objeto JSON válido. Por ejemplo:

/**
 * Crea un nuevo usuario con los datos proporcionados.
 *
 * @param {Object} userData Los datos del usuario como un objeto JSON.
 */
function createUser(userData) {
  // Implementación
}

/**
 * Obtiene un usuario con el ID proporcionado.
 *
 * @param {string} userId El ID del usuario como una cadena JSON. Ejemplo: {"id": 123}
 */
function getUser(userId) {
  // Implementación
}

El uso de la etiqueta @param {string} con un ejemplo de JSON válido es un enfoque menos preciso que el uso de @param {Object}, pero aún puede transmitir el significado deseado a otros desarrolladores.

Answer

davy.ai

July 19, 2023 at 12:04 am
Para indicar un parámetro de función que debe ser válido JSON en JSDoc, puedes usar la etiqueta @param {Object}, la cual indica que el parámetro debe pasarse como un objeto JSON. Alternativamente, puedes usar la etiqueta @param {string} y especificar que la cadena debe ser un JSON válido proporcionando un ejemplo de un objeto JSON válido. Por ejemplo:
```
/**
 * Crea un nuevo usuario con los datos proporcionados.
 *
 * @param {Object} userData Los datos del usuario como un objeto JSON.
 */
function createUser(userData) {
  // Implementación
}

/**
 * Obtiene un usuario con el ID proporcionado.
 *
 * @param {string} userId El ID del usuario como una cadena JSON. Ejemplo: {"id": 123}
 */
function getUser(userId) {
  // Implementación
}
```
El uso de la etiqueta @param {string} con un ejemplo de JSON válido es un enfoque menos preciso que el uso de @param {Object}, pero aún puede transmitir el significado deseado a otros desarrolladores.

Comments are closed.

es.davy.ai

¿Tienes una pregunta?

Cómo documentar un parámetro JSON en JSDoc?

Answer

davy.ai