issues building from source: javadoc, source encoding, and srcdir

[Carnë Draug]

Hi

I have been doing some work on the ImageJ Debian package and came
across a few issues detailed below.  Simple patches are available to
all of them.  Would be nice if they were fixed upstream.

Thank you
Carnë

---

The file ij/process/AutoThresholder.java makes use the character
U+00A0 (NO-BREAK SPACE [NBSP]) on line 652 [1].  This is a just
comment but it's causing an error during the build unless the encoding
is set.  This can be fixed by specifying the encoding on the build.xml
file.  Trivial patch available [2].

Alternatively, I guess it could be replaced with a simple space
character or maybe the escaped unicode.

---

There's some invalid javadoc on the source files.  These are the
warnings:

  [javadoc] /build/imagej-1.51p+dfsg/ij/gui/Roi.java:574: warning -
Tag @see: can't find Iterator() in ij.gui.Roi
  [javadoc] /build/imagej-1.51p+dfsg/ij/gui/Roi.java:2153: warning -
Tag @link: reference not found: Interable
  [javadoc] /build/imagej-1.51p+dfsg/ij/gui/Roi.java:2153: warning -
Tag @link: reference not found: Interable
  [javadoc] /build/imagej-1.51p+dfsg/ij/gui/PointRoi.java:714: warning
- Tag @author cannot be used in method documentation.  It can only be
used in the following types of documentation: overview, package,
class/interface.
  [javadoc] /build/imagej-1.51p+dfsg/ij/gui/Roi.java:2153: warning -
Tag @link: reference not found: Interable
  [javadoc] /build/imagej-1.51p+dfsg/ij/gui/Roi.java:606: warning -
@Returns is an unknown tag.
  [javadoc] /build/imagej-1.51p+dfsg/ij/gui/Roi.java:2153: warning -
Tag @link: reference not found: Interable
  [javadoc] /build/imagej-1.51p+dfsg/ij/gui/Roi.java:2153: warning -
Tag @author cannot be used in method documentation.  It can only be
used in the following types of documentation: overview, package,
class/interface.

There are the Interable->Iterable, Iterator()->iterator(), and
Returns->return typos.  Trivial patch available [3].

The other issue is the use of @author in the method documentation
which I'm unsure about which way ImageJ would prefer to fix.  I guess
they could be moved to the class documentation, turned it into plain
text, or just dropped completely.

---

The build.xml file sets the project root directory as srcdir for the
javac task.  However, only files in "ij/" are actually compiled.

This causes issues in Debian because quilt, the tool used by Debian to
manage patches, creates a backup of the class files within a ".pc"
directory during the build.  These class files are then picked up by
the javac task causing an error due to duplicated classes.

Debian has been solving this by patching build.xml to simply exclude
the ".pc" directory [4].  However, since only the files in "ij/" are
compiled, would be nice if srcdir was set to "ij" only.  This would
also mean that ant wouldn't have to scan the other directories for
java source files, and Debian could drop the patch.

---

[1] https://anonscm.debian.org/cgit/debian-med/imagej.git/tree/ij/process/AutoThresholder.java#n652
[2] https://anonscm.debian.org/cgit/debian-med/imagej.git/tree/debian/patches/specify-javac-encoding.patch
[3] https://anonscm.debian.org/cgit/debian-med/imagej.git/tree/debian/patches/fix-javadocs-syntax.patch
[4] https://anonscm.debian.org/cgit/debian-med/imagej.git/tree/debian/patches/exclude-quilt-from-ant.patch

--
ImageJ mailing list: http://imagej.nih.gov/ij/list.html

[ctrueden]

Hi Carnë,

Why not use ImageJA [1] instead? Many of these issues are already resolved
in that restructuring. And we can update the Jenkins job to automatically
fix any additional issues.

Regards,
Curtis

[1] https://github.com/imagej/ImageJA


--
Curtis Rueden
LOCI software architect - https://loci.wisc.edu/software
ImageJ2 lead, Fiji maintainer - https://imagej.net/User:Rueden
Did you know ImageJ has a forum? http://forum.imagej.net/


On Mon, Aug 28, 2017 at 8:37 AM, Carnë Draug <[hidden email]>
wrote:

> Hi
>
> I have been doing some work on the ImageJ Debian package and came
> across a few issues detailed below.  Simple patches are available to
> all of them.  Would be nice if they were fixed upstream.
>
> Thank you
> Carnë
>
> ---
>
> The file ij/process/AutoThresholder.java makes use the character
> U+00A0 (NO-BREAK SPACE [NBSP]) on line 652 [1].  This is a just
> comment but it's causing an error during the build unless the encoding
> is set.  This can be fixed by specifying the encoding on the build.xml
> file.  Trivial patch available [2].
>
> Alternatively, I guess it could be replaced with a simple space
> character or maybe the escaped unicode.
>
> ---
>
> There's some invalid javadoc on the source files.  These are the
> warnings:
>
>   [javadoc] /build/imagej-1.51p+dfsg/ij/gui/Roi.java:574: warning -
> Tag @see: can't find Iterator() in ij.gui.Roi
>   [javadoc] /build/imagej-1.51p+dfsg/ij/gui/Roi.java:2153: warning -
> Tag @link: reference not found: Interable
>   [javadoc] /build/imagej-1.51p+dfsg/ij/gui/Roi.java:2153: warning -
> Tag @link: reference not found: Interable
>   [javadoc] /build/imagej-1.51p+dfsg/ij/gui/PointRoi.java:714: warning
> - Tag @author cannot be used in method documentation.  It can only be
> used in the following types of documentation: overview, package,
> class/interface.
>   [javadoc] /build/imagej-1.51p+dfsg/ij/gui/Roi.java:2153: warning -
> Tag @link: reference not found: Interable
>   [javadoc] /build/imagej-1.51p+dfsg/ij/gui/Roi.java:606: warning -
> @Returns is an unknown tag.
>   [javadoc] /build/imagej-1.51p+dfsg/ij/gui/Roi.java:2153: warning -
> Tag @link: reference not found: Interable
>   [javadoc] /build/imagej-1.51p+dfsg/ij/gui/Roi.java:2153: warning -
> Tag @author cannot be used in method documentation.  It can only be
> used in the following types of documentation: overview, package,
> class/interface.
>
> There are the Interable->Iterable, Iterator()->iterator(), and
> Returns->return typos.  Trivial patch available [3].
>
> The other issue is the use of @author in the method documentation
> which I'm unsure about which way ImageJ would prefer to fix.  I guess
> they could be moved to the class documentation, turned it into plain
> text, or just dropped completely.
>
> ---
>
> The build.xml file sets the project root directory as srcdir for the
> javac task.  However, only files in "ij/" are actually compiled.
>
> This causes issues in Debian because quilt, the tool used by Debian to
> manage patches, creates a backup of the class files within a ".pc"
> directory during the build.  These class files are then picked up by
> the javac task causing an error due to duplicated classes.
>
> Debian has been solving this by patching build.xml to simply exclude
> the ".pc" directory [4].  However, since only the files in "ij/" are
> compiled, would be nice if srcdir was set to "ij" only.  This would
> also mean that ant wouldn't have to scan the other directories for
> java source files, and Debian could drop the patch.
>
> ---
>
> [1] https://anonscm.debian.org/cgit/debian-med/imagej.git/tree/
> ij/process/AutoThresholder.java#n652
> [2] https://anonscm.debian.org/cgit/debian-med/imagej.git/tree/
> debian/patches/specify-javac-encoding.patch
> [3] https://anonscm.debian.org/cgit/debian-med/imagej.git/tree/
> debian/patches/fix-javadocs-syntax.patch
> [4] https://anonscm.debian.org/cgit/debian-med/imagej.git/tree/
> debian/patches/exclude-quilt-from-ant.patch
>
> --
> ImageJ mailing list: http://imagej.nih.gov/ij/list.html
>

--
ImageJ mailing list: http://imagej.nih.gov/ij/list.html

[Carnë Draug]

On 28 August 2017 at 09:41:45 -0500, Curtis Rueden <[hidden email]> wrote:

> Hi Carnë,
>
> Why not use ImageJA [1] instead? Many of these issues are already resolved
> in that restructuring. And we can update the Jenkins job to automatically
> fix any additional issues.
>
> Regards,
> Curtis
>
> [1] https://github.com/imagej/ImageJA

Hi Curtis

I don't know why, probably historical reasons.  Debian's ImageJ
package was originally setup on 2006.  But even if Debian was to
change to package ImageJA, these issues would remain upstream and
would be nice to fix them for those building it.

Carnë

--
ImageJ mailing list: http://imagej.nih.gov/ij/list.html

[Wayne Rasband-2]

> On Aug 28, 2017, at 9:37 AM, Carnë Draug <[hidden email]> wrote:
>
> Hi
>
> I have been doing some work on the ImageJ Debian package and came
> across a few issues detailed below.  Simple patches are available to
> all of them.  Would be nice if they were fixed upstream.

These problems are fixed in the latest ImageJ daily build (1.51q39).

-wayne

> ---
>
> The file ij/process/AutoThresholder.java makes use the character
> U+00A0 (NO-BREAK SPACE [NBSP]) on line 652 [1].  This is a just
> comment but it's causing an error during the build unless the encoding
> is set.  This can be fixed by specifying the encoding on the build.xml
> file.  Trivial patch available [2].
>
> Alternatively, I guess it could be replaced with a simple space
> character or maybe the escaped unicode.
>
> ---
>
> There's some invalid javadoc on the source files.  These are the
> warnings:
>
>  [javadoc] /build/imagej-1.51p+dfsg/ij/gui/Roi.java:574: warning -
> Tag @see: can't find Iterator() in ij.gui.Roi
>  [javadoc] /build/imagej-1.51p+dfsg/ij/gui/Roi.java:2153: warning -
> Tag @link: reference not found: Interable
>  [javadoc] /build/imagej-1.51p+dfsg/ij/gui/Roi.java:2153: warning -
> Tag @link: reference not found: Interable
>  [javadoc] /build/imagej-1.51p+dfsg/ij/gui/PointRoi.java:714: warning
> - Tag @author cannot be used in method documentation.  It can only be
> used in the following types of documentation: overview, package,
> class/interface.
>  [javadoc] /build/imagej-1.51p+dfsg/ij/gui/Roi.java:2153: warning -
> Tag @link: reference not found: Interable
>  [javadoc] /build/imagej-1.51p+dfsg/ij/gui/Roi.java:606: warning -
> @Returns is an unknown tag.
>  [javadoc] /build/imagej-1.51p+dfsg/ij/gui/Roi.java:2153: warning -
> Tag @link: reference not found: Interable
>  [javadoc] /build/imagej-1.51p+dfsg/ij/gui/Roi.java:2153: warning -
> Tag @author cannot be used in method documentation.  It can only be
> used in the following types of documentation: overview, package,
> class/interface.
>
> There are the Interable->Iterable, Iterator()->iterator(), and
> Returns->return typos.  Trivial patch available [3].
>
> The other issue is the use of @author in the method documentation
> which I'm unsure about which way ImageJ would prefer to fix.  I guess
> they could be moved to the class documentation, turned it into plain
> text, or just dropped completely.
>
> ---
>
> The build.xml file sets the project root directory as srcdir for the
> javac task.  However, only files in "ij/" are actually compiled.
>
> This causes issues in Debian because quilt, the tool used by Debian to
> manage patches, creates a backup of the class files within a ".pc"
> directory during the build.  These class files are then picked up by
> the javac task causing an error due to duplicated classes.
>
> Debian has been solving this by patching build.xml to simply exclude
> the ".pc" directory [4].  However, since only the files in "ij/" are
> compiled, would be nice if srcdir was set to "ij" only.  This would
> also mean that ant wouldn't have to scan the other directories for
> java source files, and Debian could drop the patch.
>
> ---
>
> [1] https://anonscm.debian.org/cgit/debian-med/imagej.git/tree/ij/process/AutoThresholder.java#n652
> [2] https://anonscm.debian.org/cgit/debian-med/imagej.git/tree/debian/patches/specify-javac-encoding.patch
> [3] https://anonscm.debian.org/cgit/debian-med/imagej.git/tree/debian/patches/fix-javadocs-syntax.patch
> [4] https://anonscm.debian.org/cgit/debian-med/imagej.git/tree/debian/patches/exclude-quilt-from-ant.patch

--
ImageJ mailing list: http://imagej.nih.gov/ij/list.html