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

[Sanne Grinovero]

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