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

[Hardy Ferentschik]

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 at 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 at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hibernate-dev