You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@edgent.apache.org by Alexander Cook <ac...@umn.edu> on 2016/04/13 22:49:33 UTC
Javadoc warning when trying to contribute sample
Hi,
I have developed a Quarks Watson IoT Platform sample that connects to a
real range/proximity sensor using Pi4J that I would like to contribute to
Quarks. It fits in with this recipe that I wrote:
https://developer.ibm.com/recipes/tutorials/apache-quarks-on-pi-to-watson-iot-foundation/
.
I have updated the build.xml to exclude my sample since the dependency on
Pi4J leads to errors. However, I am still getting failures from Javadoc
warnings. In order to exclude the sample from Javadoc, I followed this
solution:
http://stackoverflow.com/questions/6060998/how-can-i-make-an-ant-javadoc-class-exclude-two-files
(supposedly allowing me to exclude multiple locations). Here is the code of
interest:
<fileset dir="${basedir}">
<include name="*/*/src/main/java/**/*.java"/>
<exclude name="android/**"/>
<exclude
name="samples/scenarios/src/main/java/quarks/samples/scenarios/**"/>
</fileset>
<packageset dir="${basedir}">
<include name="*/*/src/main/java/**/*.java"/>
</packageset>
This seemed to work, except now I get these warnings for code that I never
touched:
[javadoc] javadoc: warning - Multiple sources of package comments found
for package "javax.servlet"
[javadoc] javadoc: warning - Multiple sources of package comments found
for package "javax.servlet.http"
[javadoc] Standard Doclet version 1.8.0
[javadoc] Building tree for all the packages and classes...
[javadoc]
/home/streamsadmin/git/incubator-quarks/connectors/iotf/src/main/java/quarks/connectors/iotf/IotfDevice.java:60:
warning - Tag @see: reference not found: quarks.connectors.iot Quarks
generic device model
Are these warnings I should actually fix, or am I doing something wrong?
You can see the changes I have made here:
https://github.com/apache/incubator-quarks/compare/master...Alex-Cook4:master
The files of interest will be build.xml, common-build.xml,
and samples/scenarios/build.xml.
Thanks for the help!
Alex
Re: Javadoc warning when trying to contribute sample
Posted by Alexander Cook <ac...@umn.edu>.
Hi Dale, this worked:
---
One thing to perhaps try is to revert build.xml and add your new
“quarks.samples.scenarios.iotf.range.sensor” package to the existing
javadoc task param decl:
excludepackagenames="quarks.connectors.runtime,quarks.connectors.*.runtime,quarks.console.*,quarks.topology.spi.*,quarks.graph.spi.*"
---
I thought I tried that, but I must have had something else broken at the
time :-) Thank you so much for the help! I was flailing by this point...
For anyone interested, take a look at the two build.xml's and the
common-build.xml here:
https://github.com/apache/incubator-quarks/pull/98/files for how to exclude
a specific package from building and generating Javadoc. I also made it so
that the build takes place if a PI4J_LIB environment variable is set.
On Tue, Apr 19, 2016 at 10:05 AM, Dale LaBossiere <dm...@gmail.com>
wrote:
> Caveat: I’m not an “ant” wizzard :)
>
> At a high level, independent of the problem you’re encountering, the new
> exclude of "samples/scenarios/src/main/java/quarks/samples/scenarios/**”
> seems logically inappropriate since there's also the
> quarks.samples.scenarios.iotf package and IotfFullScenario.java under that
> dir which shouldn’t be excluded, right?
>
> One thing to perhaps try is to revert build.xml and add your new
> “quarks.samples.scenarios.iotf.range.sensor” package to the existing
> javadoc task param decl:
>
>
> excludepackagenames="quarks.connectors.runtime,quarks.connectors.*.runtime,quarks.console.*,quarks.topology.spi.*,quarks.graph.spi.*"
>
> Or perhaps revert build.xml and try changing the <sourcepath><dirset> to
> use an “excludes” parameter instead of nested <exclude> element? e.g.
> something like:
> <sourcepath>
> <dirset
> excludes=“android/**,samples/scenarios/**/iotf/range/sensor”>
> <include name=“*/*/src/main/java”/>
> </dirset>
> </sourcepath>
>
> I noticed the following in the ant javadoc task doc:
> "Note: many problems with running javadoc stem from command lines
> that have become too long - even though the error message doesn't give the
> slightest hint this may be the problem. If you encounter problems with the
> task, try to set the useexternalfile attribute to true first.
> Maybe your changes triggered that problem?"
>
> There seem to be other general issues with the javadoc handling. There’s
> a “Quarks SPI” group declared, but since the above is excluding the spi
> packages, that group doesn’t get generated… and there’s no spi related
> javadoc. But removing those spi exclusions causes the spi packages to
> show up in the Quarks API group and that’s no good.
>
> Since that excludepackagenames has “quarks.connectors.*.runtime”, a single
> level wildcard, the Quarks Connectors javadoc group ends up with
> quarks.connectors.wsclient.javax.websocket.runtime. It should be
> specifying a multi-level wildcard “**”.
>
> — Dale
>
> > On Apr 18, 2016, at 5:02 PM, Alexander Cook <ac...@umn.edu> wrote:
> >
> >
> > Here is the latest comparison:
> >
> https://github.com/apache/incubator-quarks/compare/master...Alex-Cook4:master
> >
> > Thanks for the help!
> >
> > Here is what I'm using for the javadoc build now:
> >
> > <fileset dir="${basedir}">
> > <include name="*/*/src/main/java/*"/>
> > <exclude name="android/**"/>
> > <exclude
> > name="samples/scenarios/src/main/java/quarks/samples/scenarios/**"/>
> > </fileset>
> > <packageset dir="${basedir}">
> > <include name="*/*/src/main/java/**"/>
> > </packageset>
>
>
Re: Javadoc warning when trying to contribute sample
Posted by Dale LaBossiere <dm...@gmail.com>.
Caveat: I’m not an “ant” wizzard :)
At a high level, independent of the problem you’re encountering, the new exclude of "samples/scenarios/src/main/java/quarks/samples/scenarios/**” seems logically inappropriate since there's also the quarks.samples.scenarios.iotf package and IotfFullScenario.java under that dir which shouldn’t be excluded, right?
One thing to perhaps try is to revert build.xml and add your new “quarks.samples.scenarios.iotf.range.sensor” package to the existing javadoc task param decl:
excludepackagenames="quarks.connectors.runtime,quarks.connectors.*.runtime,quarks.console.*,quarks.topology.spi.*,quarks.graph.spi.*"
Or perhaps revert build.xml and try changing the <sourcepath><dirset> to use an “excludes” parameter instead of nested <exclude> element? e.g. something like:
<sourcepath>
<dirset excludes=“android/**,samples/scenarios/**/iotf/range/sensor”>
<include name=“*/*/src/main/java”/>
</dirset>
</sourcepath>
I noticed the following in the ant javadoc task doc:
"Note: many problems with running javadoc stem from command lines that have become too long - even though the error message doesn't give the slightest hint this may be the problem. If you encounter problems with the task, try to set the useexternalfile attribute to true first.
Maybe your changes triggered that problem?"
There seem to be other general issues with the javadoc handling. There’s a “Quarks SPI” group declared, but since the above is excluding the spi packages, that group doesn’t get generated… and there’s no spi related javadoc. But removing those spi exclusions causes the spi packages to show up in the Quarks API group and that’s no good.
Since that excludepackagenames has “quarks.connectors.*.runtime”, a single level wildcard, the Quarks Connectors javadoc group ends up with quarks.connectors.wsclient.javax.websocket.runtime. It should be specifying a multi-level wildcard “**”.
— Dale
> On Apr 18, 2016, at 5:02 PM, Alexander Cook <ac...@umn.edu> wrote:
>
>
> Here is the latest comparison:
> https://github.com/apache/incubator-quarks/compare/master...Alex-Cook4:master
>
> Thanks for the help!
>
> Here is what I'm using for the javadoc build now:
>
> <fileset dir="${basedir}">
> <include name="*/*/src/main/java/*"/>
> <exclude name="android/**"/>
> <exclude
> name="samples/scenarios/src/main/java/quarks/samples/scenarios/**"/>
> </fileset>
> <packageset dir="${basedir}">
> <include name="*/*/src/main/java/**"/>
> </packageset>
Re: Javadoc warning when trying to contribute sample
Posted by Dale LaBossiere <dm...@gmail.com>.
Something seems amiss as the folder names are not (should not) be part of the package name. In those error msgs, the package name is really just the part starting with “quarks.javax.…” and “quarks.connectors.wsclient…."
It might be interesting to try removing the “-“ in the folder names to see what happens, but since the javadoc processing was previously handling the wsclient-javax.websocket/src/main/java and javax.websocket-client/src/main/java folders without any problems it seems like the problem must be elsewhere.
I’ll look at your changes.
— Dale
> On Apr 18, 2016, at 5:02 PM, Alexander Cook <ac...@umn.edu> wrote:
>
> I've been digging into this more.
>
> The errors are resulting because of a package name that includes a dash in
> it. Shouldn't the folder names be something like javax.websocket.client
> instead of -client?
> [javadoc] javadoc: error - Illegal package name:
> "connectors.javax.websocket-client.src.main.java.quarks.javax.websocket.impl"
> [javadoc] javadoc: error - Illegal package name:
> "connectors.wsclient-javax.websocket.src.main.java.quarks.connectors.wsclient.javax.websocket"
> [javadoc] javadoc: error - Illegal package name:
> "connectors.wsclient-javax.websocket.src.main.java.quarks.connectors.wsclient.javax.websocket.runtime"
>
> I also get this warning:
> [javadoc] javadoc: warning - No source files for package
> connectors.quarks.javax.websocket.src.main.java.quarks.javax.websocket
>
> I'm not sure why I'm getting that warning since there actually is a source
> file there: QuarksSslContainerProvider.java
>
> Do people agree that the setup is wrong? Should I change the folder names
> in the connectors package? Or is this a problem with how I'm doing the
> build since the folder names at that level aren't really part of the
> package name?
>
> Here is the latest comparison:
> https://github.com/apache/incubator-quarks/compare/master...Alex-Cook4:master
>
> Thanks for the help!
>
> Here is what I'm using for the javadoc build now:
>
> <fileset dir="${basedir}">
> <include name="*/*/src/main/java/*"/>
> <exclude name="android/**"/>
> <exclude
> name="samples/scenarios/src/main/java/quarks/samples/scenarios/**"/>
> </fileset>
> <packageset dir="${basedir}">
> <include name="*/*/src/main/java/**"/>
> </packageset>
>
>
> On Wed, Apr 13, 2016 at 3:49 PM, Alexander Cook <ac...@umn.edu> wrote:
>
>> Hi,
>>
>> I have developed a Quarks Watson IoT Platform sample that connects to a
>> real range/proximity sensor using Pi4J that I would like to contribute to
>> Quarks. It fits in with this recipe that I wrote:
>> https://developer.ibm.com/recipes/tutorials/apache-quarks-on-pi-to-watson-iot-foundation/
>> .
>>
>> I have updated the build.xml to exclude my sample since the dependency on
>> Pi4J leads to errors. However, I am still getting failures from Javadoc
>> warnings. In order to exclude the sample from Javadoc, I followed this
>> solution:
>> http://stackoverflow.com/questions/6060998/how-can-i-make-an-ant-javadoc-class-exclude-two-files
>> (supposedly allowing me to exclude multiple locations). Here is the code of
>> interest:
>>
>> <fileset dir="${basedir}">
>> <include name="*/*/src/main/java/**/*.java"/>
>> <exclude name="android/**"/>
>> <exclude
>> name="samples/scenarios/src/main/java/quarks/samples/scenarios/**"/>
>> </fileset>
>> <packageset dir="${basedir}">
>> <include name="*/*/src/main/java/**/*.java"/>
>> </packageset>
>>
>> This seemed to work, except now I get these warnings for code that I never
>> touched:
>>
>> [javadoc] javadoc: warning - Multiple sources of package comments found
>> for package "javax.servlet"
>> [javadoc] javadoc: warning - Multiple sources of package comments found
>> for package "javax.servlet.http"
>> [javadoc] Standard Doclet version 1.8.0
>> [javadoc] Building tree for all the packages and classes...
>> [javadoc]
>> /home/streamsadmin/git/incubator-quarks/connectors/iotf/src/main/java/quarks/connectors/iotf/IotfDevice.java:60:
>> warning - Tag @see: reference not found: quarks.connectors.iot Quarks
>> generic device model
>>
>> Are these warnings I should actually fix, or am I doing something wrong?
>>
>> You can see the changes I have made here:
>> https://github.com/apache/incubator-quarks/compare/master...Alex-Cook4:master
>>
>>
>> The files of interest will be build.xml, common-build.xml,
>> and samples/scenarios/build.xml.
>> Thanks for the help!
>>
>> Alex
>>
Re: Javadoc warning when trying to contribute sample
Posted by Alexander Cook <ac...@umn.edu>.
I've been digging into this more.
The errors are resulting because of a package name that includes a dash in
it. Shouldn't the folder names be something like javax.websocket.client
instead of -client?
[javadoc] javadoc: error - Illegal package name:
"connectors.javax.websocket-client.src.main.java.quarks.javax.websocket.impl"
[javadoc] javadoc: error - Illegal package name:
"connectors.wsclient-javax.websocket.src.main.java.quarks.connectors.wsclient.javax.websocket"
[javadoc] javadoc: error - Illegal package name:
"connectors.wsclient-javax.websocket.src.main.java.quarks.connectors.wsclient.javax.websocket.runtime"
I also get this warning:
[javadoc] javadoc: warning - No source files for package
connectors.quarks.javax.websocket.src.main.java.quarks.javax.websocket
I'm not sure why I'm getting that warning since there actually is a source
file there: QuarksSslContainerProvider.java
Do people agree that the setup is wrong? Should I change the folder names
in the connectors package? Or is this a problem with how I'm doing the
build since the folder names at that level aren't really part of the
package name?
Here is the latest comparison:
https://github.com/apache/incubator-quarks/compare/master...Alex-Cook4:master
Thanks for the help!
Here is what I'm using for the javadoc build now:
<fileset dir="${basedir}">
<include name="*/*/src/main/java/*"/>
<exclude name="android/**"/>
<exclude
name="samples/scenarios/src/main/java/quarks/samples/scenarios/**"/>
</fileset>
<packageset dir="${basedir}">
<include name="*/*/src/main/java/**"/>
</packageset>
On Wed, Apr 13, 2016 at 3:49 PM, Alexander Cook <ac...@umn.edu> wrote:
> Hi,
>
> I have developed a Quarks Watson IoT Platform sample that connects to a
> real range/proximity sensor using Pi4J that I would like to contribute to
> Quarks. It fits in with this recipe that I wrote:
> https://developer.ibm.com/recipes/tutorials/apache-quarks-on-pi-to-watson-iot-foundation/
> .
>
> I have updated the build.xml to exclude my sample since the dependency on
> Pi4J leads to errors. However, I am still getting failures from Javadoc
> warnings. In order to exclude the sample from Javadoc, I followed this
> solution:
> http://stackoverflow.com/questions/6060998/how-can-i-make-an-ant-javadoc-class-exclude-two-files
> (supposedly allowing me to exclude multiple locations). Here is the code of
> interest:
>
> <fileset dir="${basedir}">
> <include name="*/*/src/main/java/**/*.java"/>
> <exclude name="android/**"/>
> <exclude
> name="samples/scenarios/src/main/java/quarks/samples/scenarios/**"/>
> </fileset>
> <packageset dir="${basedir}">
> <include name="*/*/src/main/java/**/*.java"/>
> </packageset>
>
> This seemed to work, except now I get these warnings for code that I never
> touched:
>
> [javadoc] javadoc: warning - Multiple sources of package comments found
> for package "javax.servlet"
> [javadoc] javadoc: warning - Multiple sources of package comments found
> for package "javax.servlet.http"
> [javadoc] Standard Doclet version 1.8.0
> [javadoc] Building tree for all the packages and classes...
> [javadoc]
> /home/streamsadmin/git/incubator-quarks/connectors/iotf/src/main/java/quarks/connectors/iotf/IotfDevice.java:60:
> warning - Tag @see: reference not found: quarks.connectors.iot Quarks
> generic device model
>
> Are these warnings I should actually fix, or am I doing something wrong?
>
> You can see the changes I have made here:
> https://github.com/apache/incubator-quarks/compare/master...Alex-Cook4:master
>
>
> The files of interest will be build.xml, common-build.xml,
> and samples/scenarios/build.xml.
> Thanks for the help!
>
> Alex
>