用Java记录第三方库的使用的标准/官方方式是什么？

Question

When writing a javadoc comment preceding a class in which a third party library is used, what's the standard/official way for documenting the third party library name, version and web address where it can be downloaded? Should it be mentioned in the description or among the block tags (using @see or a custom tag)?

Answer 1

Depends on what you want to accomplish.

The version and download link should be in the configuration file of your dependency management tool (such as maven). That way, the documentation is never out of date, and not repeated in every class that happens to use that particular API.

To discover which classes use which API, import statements work quite nicely (yes, one can bypass import statements by using qualified class names, but very few people do, as that makes the source code very hard to read). Alternatively, simply remove the library from the classpath, and see where compilation errors occur.

I recommend against documenting this in the javadoc, as the caller of your class should be agnostic of its implementation. That is, I consider APIs used to be an implementation detail a caller should not know - and what the caller should not know should not be mixed with the things he must know.

Answer 2

Should it be mentioned in the description or among the block tags (using @see or a custom tag)?

Just mention it somewhere in the description, (personally) preferably towards the end. Don't get into defining custom tags for something like this, it's not worth the hassle. The important thing is that (if necessary) the information is there. There's no set convention for doing this.

I say "if necessary" deliberately - most of the time I'd say this simply isn't needed. However, if dealing with a library that's not widely known, not in Maven and / or has the tendency to make breaking changes between releases, then it would arguably be worth documenting this at least somewhere.