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

[Gunnar Morling]

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