Is there a way to define 'javadoc types' - custom parameters for members?

Question

The use case I can think of is the following:

In a typical application, there are usually many members of a certain category, e.g., a web application contains many constants attribute keys, Action classes, services, etc. For each category, to maintain consistency, it is useful to document them consistently.

Consider the constants used for attribute keys:

/**
 * Request scope attribute key of the {@link com.acme.domain.User} object added by the {@link LoginAction}.
 */
public static final String USER_KEY = "com.acme.web.user";

Each attribute key should typically document its scope, the type of Object stored under it, who sets it, and who it's for. A 'javadoc type / category' would be used as follows:

/**
 * @AttributeKey
 * @scope request
 * @type com.acme.domain.User
 * @source com.acme.web.action.LoginAction#processLogin()
 * @for HomePage.jsp
 */
public static final String USER_KEY = ...;

Of course, the rendered documentation tags should be translated to English for rendering. An important part of the above scheme is the @AttributeKey tag - this would force documentation writers to include all the required fields or face warning messages.

I'm almost positive that such a thing does not exist for Java, but would it be worthwhile and what other languages / documentation systems have such a feature?

Answer 1

I should think that annotations would be a better match for the kind of thing you're talking about (semantics, constraints, contracts, etc.).