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

[Gunnar Morling]

2013/7/31 Hardy Ferentschik <hardy at 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 <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
>
>