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

[Emmanuel Bernard]

For the record, I side with Gunnar in relaxing this. I actually did not see this thread and opened a issue for it this very morning.
In most situations we reference classes local to the module via {@link} and the fully qualified class name is very annoying and very long.


On 31 juil. 2013, at 09:33, Gunnar Morling 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