Comment Standards

EasyApi generates API documentation based on Javadoc, KDoc, and ScalaDoc.

Javadoc

Javadoc is the standard documentation comment format in Java. EasyApi uses Javadoc to extract API names, descriptions, and parameter information.

Basic Format

/**
 * API name (first line)
 *
 * API detailed description
 *
 * @param name Parameter description
 * @return Return value description
 */
@GetMapping("/hello")
public String hello(@RequestParam String name) {
    return "Hello " + name;
}

Common Tags

Tag	Purpose	Example
@param	Parameter description	@param name Username
@return	Return value description	@return Greeting message
@deprecated	Mark as deprecated	@deprecated Use helloV2 instead
@module	API grouping	@module User Management
@mock	Mock data	@mock admin
@see	See also	@see User

Record Components

A Java record component carries no per-field comment, so document the components with @param tags on the record's own Javadoc. Since v3.2.2 they are exported as the field descriptions, in every channel:

/**
 * User record
 *
 * @param id User ID
 * @param name User name
 */
public record UserRecord(Long id, String name) {}

Multiple Return Types

Use multiple @return tags to document different response scenarios:

/**
 * Get user info
 * @return success {@link User} User info
 * @return unauthorized {@link Error} Not authenticated
 */
@GetMapping("/users/{id}")
public Object getUser(@PathVariable Long id) {
    // ...
}

KDoc

KDoc is the documentation comment format in Kotlin, similar to Javadoc but supports Markdown syntax.

Basic Format

/**
 * API name
 *
 * API detailed description
 *
 * @param name Parameter description
 * @return Return value description
 */
@GetMapping("/hello")
fun hello(@RequestParam name: String): String {
    return "Hello $name"
}

KDoc descriptions are also used as API titles and as candidates for API folder names. Writing a clear first paragraph for a Kotlin API or class therefore improves both exported naming and grouping; explicit name or folder rules still take precedence.

ScalaDoc

ScalaDoc is the documentation comment format in Scala. EasyApi supports ScalaDoc for Scala projects.

Basic Format

/**
 * API name
 *
 * API detailed description
 *
 * @param name Parameter description
 * @return Return value description
 */
@GetMapping(path = Array("/hello"))
def hello(@RequestParam name: String): String = {
  s"Hello $name"
}