Recently, I started using compodoc to document my app and I am facing some challenges in writing clean code while documenting the openWeather API interface.
I attempted to use the conventional @property JSDoc marker but it does not seem to work well with compodoc. In order to achieve the desired outcome, I had to structure it like this:
/**
* Weather information
*/
interface CityWeather {
/**
* Weather condition id
*/
id: number;
/**
* Group of weather parameters (Rain, Snow, Extreme etc.)
*/
main: string;
/**
* Weather condition within the group
*/
description: string;
/**
* Weather icon id
*/
icon: string;
}
I prefer to have the comments only at the beginning of the code rather than above each property, similar to the older JSDoc @property {type} [name]. Is there a cleaner or more efficient way to do this?
/**
* Weather information
*
* @property id Weather condition id
* @property main Group of weather parameters (Rain, Snow, Extreme etc.)
* @property description Weather condition within the group
* @property icon Weather icon id
*/
interface CityWeather {
id: number;
main: string;
description: string;
icon: string;
}
A Small Edit from my end
You can streamline the comments by keeping everything within a one-line /** */, like so:
/** Weather information */
export interface CityWeather {
/** Weather condition id */
id: number;
/** Group of weather parameters (Rain, Snow, Extreme etc.) */
main: string;
/** Weather condition within the group */
description: string;
/** Weather icon id */
icon: string;
}