2013/7/31 Hardy Ferentschik <ha...@hibernate.org> > Hi, > > Personally I prefer to include a class via fully qualified name if it is > only used in the javadocs. > I think the readability does not suffer too much and adding an actual > import has actually > runtime consequences. We already had cases where a javadoc import caused a > hard link > between code which is otherwise decoupled. >
WDYM exactly by "hard link" in this context? Is it about referencing a type from an optional dependency which might not be present at runtime? I just tried out this scenario (adding an import statement just for JavaDoc to a type which is not present at runtime) and still could execute the importing class without problems. Only when accessing the imported type in the actual code I'm getting a CNFE. But this might be specific to the VM in use, not sure. So if you guys are concerned about this case then let's better keep it as is. > > Even the check stye documentation recommends against it in the > configuration > of Unused Imports - > http://checkstyle.sourceforge.net/config_imports.html#UnusedImports. > > --Hardy > > > On 31 Jan 2013, at 9:33 AM, Gunnar Morling <gun...@hibernate.org> wrote: > > > Hi, > > > > Currently CheckStyle raises an error due to an "unused import" if a class > > imports types which are only referenced in JavaDoc comments. This issue > > occurs for instance when referring to a super type in the comments while > > only sub-types are used in the actual code: > > > > /** > > * This factory creates {@link Service} objects. > > */ > > public class ServiceFactory { > > > > FooService getFooService() { ... } > > } > > > > Another example is "high-level" documentation on a central type of an API > > (e.g. its entry point) which refers to types actually used by specific > > parts of the API but not the entry point itself. In that case it can > still > > make sense to mention these types in the high-level docs. > > > > To work around the issue one could use the FQN in the JavaDoc or just > > format it as {@code}, but both makes up for less readable documentation > IMO. > > > > Personally I don't see a problem with this kind of import and thus > suggest > > to loosen that CS rule accordingly (it can be configured to take JavaDocs > > into account). WDYT? > > > > --Gunnar > > _______________________________________________ > > hibernate-dev mailing list > > hibernate-dev@lists.jboss.org > > https://lists.jboss.org/mailman/listinfo/hibernate-dev > > _______________________________________________ hibernate-dev mailing list hibernate-dev@lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev
