Is there a way to define 'javadoc types' - custom parameters for members?
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.
Consid开发者_开发知识库er 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?
I should think that annotations would be a better match for the kind of thing you're talking about (semantics, constraints, contracts, etc.).
精彩评论