You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@oodt.apache.org by Cameron Goodale <si...@gmail.com> on 2012/08/13 16:02:37 UTC
1100+ Javadoc Warnings...
Hey Brian, (I am addressing you because my focus for javadoc clean up is
the cli component)
and Paul (since you are the maven guru)
90% of the javadoc problems we (Mike Joyce and I) are finding are related
to the javadoc tool not searching within the java package to find and fill
in a complete reference.
Here is an example of the DIFF I created from the cli module after cleaning
up over 100 javadoc errors. 2 or 3 were merely typos, but most of them
where like these:
===================================================================
--- src/main/java/org/apache/oodt/cas/cli/option/ActionCmdLineOption.java
(revision
1371572)
+++ src/main/java/org/apache/oodt/cas/cli/option/ActionCmdLineOption.java
(working
copy)
@@ -17,7 +17,7 @@
package org.apache.oodt.cas.cli.option;
/**
- * {@link CmdLineOption} for specifying {@link CmdLineAction}.
*+ * {@link CmdLineOption} for specifying {@link
org.apache.oodt.cas.cli.action.CmdLineAction}.*
*
* @author bfoster (Brian Foster)
*/
Index:
src/main/java/org/apache/oodt/cas/cli/option/validator/CmdLineOptionValidator.java
===================================================================
---
src/main/java/org/apache/oodt/cas/cli/option/validator/CmdLineOptionValidator.java
(revision
1371572)
+++
src/main/java/org/apache/oodt/cas/cli/option/validator/CmdLineOptionValidator.java
(working
copy)
@@ -20,7 +20,7 @@
import org.apache.oodt.cas.cli.option.CmdLineOptionInstance;
/**
- * Validator for specified values of {@link CmdLineOption}s.
*+ * Validator for specified values of {@link
org.apache.oodt.cas.cli.option.CmdLineOption}s.*
*
* @author bfoster (Brian Foster)
*/
So it seems like we have to use fully qualified package names
when referencing methods and objects within javadocs. I was really hoping
that some kinda maven plugin magic would be able to search and resolve
these paths for us during the build process.
I have tried a couple different things like using "mvn javadoc:fix" but
that doesn't seem to do much.
So if anyone has any ideas to try on this I am all ears.
Thanks,
Cameron
--
Sent from a Tin Can attached to a String
Re: 1100+ Javadoc Warnings...
Posted by Cameron Goodale <go...@apache.org>.
Hey Brian,
I think the real issue is with the setup of the maven javadoc plugin.
There is a way to ask the javadoc to search within the current project to
create the links between docs, I just haven't been able to get it working
for the maven plugin. I agree that adding the full path will be incredibly
cumbersome so i hope with some maven magic 99% of the javadoc warnings will
go away.
Thanks for the reply to this.
-Cam
On Fri, Aug 24, 2012 at 10:52 PM, Brian Foster <ho...@me.com> wrote:
> hey cameron... sorry totally forgot about this email... i think you can
> just add an import statement for the {@link <classname>}... putting the
> full path in the {@link} will just make the javadoc messy looking... i will
> try to fix my eclipse setup so it complains about that and asks me to
> import so i remember to do it from now on
>
> -brian
>
> On Aug 13, 2012, at 7:02 AM, Cameron Goodale wrote:
>
> > Hey Brian, (I am addressing you because my focus for javadoc clean up is
> > the cli component)
> > and Paul (since you are the maven guru)
> >
> > 90% of the javadoc problems we (Mike Joyce and I) are finding are related
> > to the javadoc tool not searching within the java package to find and
> fill
> > in a complete reference.
> >
> > Here is an example of the DIFF I created from the cli module after
> cleaning
> > up over 100 javadoc errors. 2 or 3 were merely typos, but most of them
> > where like these:
> >
> > ===================================================================
> > --- src/main/java/org/apache/oodt/cas/cli/option/ActionCmdLineOption.java
> > (revision
> > 1371572)
> > +++ src/main/java/org/apache/oodt/cas/cli/option/ActionCmdLineOption.java
> > (working
> > copy)
> > @@ -17,7 +17,7 @@
> > package org.apache.oodt.cas.cli.option;
> >
> > /**
> > - * {@link CmdLineOption} for specifying {@link CmdLineAction}.
> > *+ * {@link CmdLineOption} for specifying {@link
> > org.apache.oodt.cas.cli.action.CmdLineAction}.*
> > *
> > * @author bfoster (Brian Foster)
> > */
> > Index:
> >
> src/main/java/org/apache/oodt/cas/cli/option/validator/CmdLineOptionValidator.java
> > ===================================================================
> > ---
> >
> src/main/java/org/apache/oodt/cas/cli/option/validator/CmdLineOptionValidator.java
> > (revision
> > 1371572)
> > +++
> >
> src/main/java/org/apache/oodt/cas/cli/option/validator/CmdLineOptionValidator.java
> > (working
> > copy)
> > @@ -20,7 +20,7 @@
> > import org.apache.oodt.cas.cli.option.CmdLineOptionInstance;
> >
> > /**
> > - * Validator for specified values of {@link CmdLineOption}s.
> > *+ * Validator for specified values of {@link
> > org.apache.oodt.cas.cli.option.CmdLineOption}s.*
> > *
> > * @author bfoster (Brian Foster)
> > */
> >
> > So it seems like we have to use fully qualified package names
> > when referencing methods and objects within javadocs. I was really
> hoping
> > that some kinda maven plugin magic would be able to search and resolve
> > these paths for us during the build process.
> >
> > I have tried a couple different things like using "mvn javadoc:fix" but
> > that doesn't seem to do much.
> >
> > So if anyone has any ideas to try on this I am all ears.
> >
> >
> >
> > Thanks,
> >
> >
> > Cameron
> >
> >
> > --
> >
> > Sent from a Tin Can attached to a String
>
>
Re: 1100+ Javadoc Warnings...
Posted by Brian Foster <ho...@me.com>.
hey cameron... sorry totally forgot about this email... i think you can just add an import statement for the {@link <classname>}... putting the full path in the {@link} will just make the javadoc messy looking... i will try to fix my eclipse setup so it complains about that and asks me to import so i remember to do it from now on
-brian
On Aug 13, 2012, at 7:02 AM, Cameron Goodale wrote:
> Hey Brian, (I am addressing you because my focus for javadoc clean up is
> the cli component)
> and Paul (since you are the maven guru)
>
> 90% of the javadoc problems we (Mike Joyce and I) are finding are related
> to the javadoc tool not searching within the java package to find and fill
> in a complete reference.
>
> Here is an example of the DIFF I created from the cli module after cleaning
> up over 100 javadoc errors. 2 or 3 were merely typos, but most of them
> where like these:
>
> ===================================================================
> --- src/main/java/org/apache/oodt/cas/cli/option/ActionCmdLineOption.java
> (revision
> 1371572)
> +++ src/main/java/org/apache/oodt/cas/cli/option/ActionCmdLineOption.java
> (working
> copy)
> @@ -17,7 +17,7 @@
> package org.apache.oodt.cas.cli.option;
>
> /**
> - * {@link CmdLineOption} for specifying {@link CmdLineAction}.
> *+ * {@link CmdLineOption} for specifying {@link
> org.apache.oodt.cas.cli.action.CmdLineAction}.*
> *
> * @author bfoster (Brian Foster)
> */
> Index:
> src/main/java/org/apache/oodt/cas/cli/option/validator/CmdLineOptionValidator.java
> ===================================================================
> ---
> src/main/java/org/apache/oodt/cas/cli/option/validator/CmdLineOptionValidator.java
> (revision
> 1371572)
> +++
> src/main/java/org/apache/oodt/cas/cli/option/validator/CmdLineOptionValidator.java
> (working
> copy)
> @@ -20,7 +20,7 @@
> import org.apache.oodt.cas.cli.option.CmdLineOptionInstance;
>
> /**
> - * Validator for specified values of {@link CmdLineOption}s.
> *+ * Validator for specified values of {@link
> org.apache.oodt.cas.cli.option.CmdLineOption}s.*
> *
> * @author bfoster (Brian Foster)
> */
>
> So it seems like we have to use fully qualified package names
> when referencing methods and objects within javadocs. I was really hoping
> that some kinda maven plugin magic would be able to search and resolve
> these paths for us during the build process.
>
> I have tried a couple different things like using "mvn javadoc:fix" but
> that doesn't seem to do much.
>
> So if anyone has any ideas to try on this I am all ears.
>
>
>
> Thanks,
>
>
> Cameron
>
>
> --
>
> Sent from a Tin Can attached to a String