开发者

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.).

0

上一篇:

下一篇:

精彩评论

暂无评论...
验证码 换一张
取 消

最新问答

问答排行榜