Re: [hibernate-dev] OGM: CheckStyle and imports due to JavaDoc comments

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. 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 <gunnar(a)hibernate.org&gt; 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(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/hibernate-dev _______________________________________________ hibernate-dev mailing list hibernate-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev