[Hawkular-dev] Coming to Parent: publishing JavaDoc and sources via Maven

[John Mazzitelli]

FWIW, the only way I would say we do javadoc checks is if we really javadoc things. I don't want javadoc to just look like this so people can pass the checks:

/**
 * @param firstArg
 * @param secondArg
 * @return int
 */

Because if that's all its going to look like (just to get it to pass the checks) the javadoc is useless, increases the size of the .java files for no reason, and it's just yet another "check" phase we need to worry about and fix during builds with no value-add.

If the Javadoc is going to be fully fleshed out with REAL comments about what the parameters are, what it returns, what the method does, yadda yadda, then OK. But don't do this just for the sake of saying "we have javadoc jars" if the javadocs don't add anything helpful.

And FWIW#2, I find source jars more valuable than javadoc jars.

$0.02 deposited.

----- Original Message -----
> 
> Hi Peter, to get an idea of the type and volume of issues this will report,
> can you list the current bus warnings you're seeing?
> 
> 
> On 3/30/2015 9:37 AM, Peter Palaga wrote:
> 
> 
> 
> Hi *, there is a question about handling JavaDoc checks violations at
> the bottom.
> 
> I have added maven-javadoc-plugin and maven-source-plugin to the new
> "release" profile in Hawkular Parent.
> https://github.com/hawkular/hawkular-parent-pom/pull/20 I have tested the
> above only with Hawkular Bus. Therefore, please test
> the setup with your Hawkular component:
> * Make whatever is appropriate to make your component use the pom from
> https://github.com/hawkular/hawkular-parent-pom/pull/20 * Invoke
> 
>    mvn clean install -Prelease
> 
> * Figure out, how many "[WARNING] Javadoc Warnings" are there.
> * Look into target folders if *-javadoc.jar and *-sources.jar files were
> generated
> 
> 
> == Handling JavaDoc checks violations
> 
> The present setup turns all javadoc violations into warnings using
> -Xdoclint:none [1]. I can only say that there *are* violations in Bus.
> 
> I think that we should aim at having no violations at all - i.e. that
> the components should be given a week or two to fix and that we should
> switch to -Xdoclint:all after that. WDYT?
> 
> More about -Xdoclint can be found in [2].
> 
> Thanks,
> 
> Peter
> 
> [1]
> https://github.com/hawkular/hawkular-parent-pom/commit/d54a8d03b4ef251d594f1cc4ff3fadfa4a1d4dd3#diff-600376dffeb79835ede4a0b285078036R110
> [2] http://docs.oracle.com/javase/8/docs/technotes/tools/unix/javac.html
> _______________________________________________
> hawkular-dev mailing list hawkular-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hawkular-dev
> 
> 
> _______________________________________________
> hawkular-dev mailing list
> hawkular-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hawkular-dev
>