Re: [hibernate-dev] OGM: CheckStyle and imports due to JavaDoc comments
2013/7/31 Hardy Ferentschik <hardy(a)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(a)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(a)lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hibernate-dev