I had a very minor preference for declaring the import over writing verbose javadocs, but Hardy's point on decoupling is very interesting. +1 to keep the error
On 31 July 2013 09:08, Hardy Ferentschik <ha...@hibernate.org> wrote: > 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 <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 _______________________________________________ hibernate-dev mailing list hibernate-dev@lists.jboss.org https://lists.jboss.org/mailman/listinfo/hibernate-dev
