[libvirt] [PATCH] [libvirt-java] Fix javadoc warnings.
Hi. I sent a few mails on friday, 6th July, via gmane.org but they haven't made it to the list yet. As I'm a subscriber now, I'm resending them directly. Sorry for any duplicates in advance. Here's a patch fixing these javadoc warnings: --- [javadoc] x:\src\libvirt-java\src\main\java\org\libvirt\Connect.java:387: warning - @return tag has no arguments. [javadoc] x:\src\libvirt-java\src\main\java\org\libvirt\Connect.java:644: warning - @return tag has no arguments. [javadoc] x:\src\libvirt-java\src\main\java\org\libvirt\Connect.java:658: warning - @return tag has no arguments. [javadoc] x:\src\libvirt-java\src\main\java\org\libvirt\Domain.java:681: warning - @return tag has no arguments. [javadoc] x:\src\libvirt-java\src\main\java\org\libvirt\Domain.java:795: warning - Tag @see: reference not found: http [javadoc] ://www.libvirt.org/html/libvirt-libvirt.html#virDomainMigrateToURI [javadoc] x:\src\libvirt-java\src\main\java\org\libvirt\DomainSnapshot.java:40: warning - @return tag has no arguments. [javadoc] x:\src\libvirt-java\src\main\java\org\libvirt\StoragePool.java:349: warning - @return tag has no arguments. [javadoc] x:\src\libvirt-java\src\main\java\org\libvirt\Stream.java:130: warning - Tag @see:illegal character: "58" in "http://www.libvirt.org/html/libvi rt-libvirt.html#virStreamRecvAll" [javadoc] x:\src\libvirt-java\src\main\java\org\libvirt\Stream.java:130: warning - Tag @see:illegal character: "47" in "http://www.libvirt.org/html/libvi rt-libvirt.html#virStreamRecvAll" [javadoc] x:\src\libvirt-java\src\main\java\org\libvirt\Stream.java:130: warning - Tag @see:illegal character: "47" in "http://www.libvirt.org/html/libvi rt-libvirt.html#virStreamRecvAll" [javadoc] x:\src\libvirt-java\src\main\java\org\libvirt\Stream.java:130: warning - Tag @see:illegal character: "47" in "http://www.libvirt.org/html/libvi rt-libvirt.html#virStreamRecvAll" [javadoc] x:\src\libvirt-java\src\main\java\org\libvirt\Stream.java:130: warning - Tag @see:illegal character: "47" in "http://www.libvirt.org/html/libvi rt-libvirt.html#virStreamRecvAll" [javadoc] x:\src\libvirt-java\src\main\java\org\libvirt\Stream.java:130: warning - Tag @see:illegal character: "45" in "http://www.libvirt.org/html/libvi rt-libvirt.html#virStreamRecvAll" [javadoc] x:\src\libvirt-java\src\main\java\org\libvirt\Stream.java:130: warning - Tag @see: reference not found: http://www.libvirt.org/html/libvirt-lib virt.html#virStreamRecvAll --- --- diff --git a/src/main/java/org/libvirt/Connect.java b/src/main/java/org/libvirt/Connect.java index 77336f0..de75f20 100644 --- a/src/main/java/org/libvirt/Connect.java +++ b/src/main/java/org/libvirt/Connect.java @@ -381,7 +381,7 @@ public class Connect { * Documentation</a> * @param callbackID * the callback to deregister - * @return + * @return 0 on success, -1 on failure * @throws LibvirtException */ public int domainEventDeregister(int callbackID) throws LibvirtException { @@ -400,7 +400,7 @@ public class Connect { int action); } - private interface GenericCallback { + protected interface GenericCallback { void eventCallback(Connect connect, Domain domain); } public interface RebootCallback extends GenericCallback { @@ -638,7 +638,7 @@ public class Connect { * domain configuration file describing the domain. The format of the native * data is hypervisor dependant. * - * @return + * @return domain XML as String, or {@code null} on error * @throws LibvirtException */ public String domainXMLFromNative(String nativeFormat, String nativeConfig, int flags) throws LibvirtException { @@ -652,7 +652,7 @@ public class Connect { * native configuration file describing the domain. The format of the native * data is hypervisor dependant. * - * @return + * @return domain XML as String, or {@code null} on error * @throws LibvirtException */ public String domainXMLToNative(String nativeFormat, String domainXML, int flags) throws LibvirtException { diff --git a/src/main/java/org/libvirt/Domain.java b/src/main/java/org/libvirt/Domain.java index fd7a03a..fe9f3b0 100644 --- a/src/main/java/org/libvirt/Domain.java +++ b/src/main/java/org/libvirt/Domain.java @@ -675,7 +675,7 @@ public class Domain { * @see <a * href="http://www.libvirt.org/html/libvirt-libvirt.html#virDomainManagedSaveRemove">Libvirt * Documentation</a> - * @return + * @return 0 in case of success, and -1 in case of error * @throws LibvirtException */ public int managedSaveRemote() throws LibvirtException { @@ -778,8 +778,9 @@ public class Domain { * Migrate the domain object from its current host to the destination host * given by duri. * - * @see http - * ://www.libvirt.org/html/libvirt-libvirt.html#virDomainMigrateToURI + * @see <a + * href="http://www.libvirt.org/html/libvirt-libvirt.html#virDomainMigrateToURI"> + * virDomainMigrateToURI</a> * * @param uri * The destination URI diff --git a/src/main/java/org/libvirt/DomainSnapshot.java b/src/main/java/org/libvirt/DomainSnapshot.java index e9a23d6..add6830 100644 --- a/src/main/java/org/libvirt/DomainSnapshot.java +++ b/src/main/java/org/libvirt/DomainSnapshot.java @@ -34,7 +34,7 @@ public class DomainSnapshot { * Documentation</a> * @param flags * controls teh deletion - * @return + * @return 0 if the selected snapshot(s) were successfully deleted, -1 on error. * @throws LibvirtException */ public int delete(int flags) throws LibvirtException { diff --git a/src/main/java/org/libvirt/StoragePool.java b/src/main/java/org/libvirt/StoragePool.java index a3d59a9..0328d8c 100644 --- a/src/main/java/org/libvirt/StoragePool.java +++ b/src/main/java/org/libvirt/StoragePool.java @@ -343,7 +343,7 @@ public class StoragePool { * as input. Information for the new volume (name, perms) are passed via a * typical volume XML description. * - * @return + * @return The storage volume, or {@code null} on error. * @throws LibvirtException */ public StorageVol storageVolCreateXMLFrom(String xmlDesc, StorageVol cloneVolume, int flags) diff --git a/src/main/java/org/libvirt/Stream.java b/src/main/java/org/libvirt/Stream.java index fdef3a4..6374567 100644 --- a/src/main/java/org/libvirt/Stream.java +++ b/src/main/java/org/libvirt/Stream.java @@ -121,7 +121,7 @@ public class Stream { /** * Batch receive method * - * @see http://www.libvirt.org/html/libvirt-libvirt.html#virStreamRecvAll + * @see <a href="http://www.libvirt.org/html/libvirt-libvirt.html#virStreamRecvAll">virStreamRecvAll</a> * @param handler * the callback handler * @return 0 if successfule, -1 otherwise --- Best regards, Claudio -- AV-Test GmbH, Henricistraße 20, 04155 Leipzig, Germany Phone: +49 341 265 310 19 Web:<http://www.av-test.org> Eingetragen am / Registered at: Amtsgericht Stendal (HRB 114076) Geschaeftsfuehrer (CEO): Andreas Marx, Guido Habicht, Maik Morgenstern
ping... ?! Isn't this the appropriate list? What's the status of libvirt-java? Best Regards, Claudio At Mon, 09 Jul 2012 10:23:42 +0200, Claudio Bley wrote:
Here's a patch fixing these javadoc warnings:
--- [javadoc] x:\src\libvirt-java\src\main\java\org\libvirt\Connect.java:387: warning - @return tag has no arguments. [javadoc] x:\src\libvirt-java\src\main\java\org\libvirt\Connect.java:644: warning - @return tag has no arguments. [javadoc] x:\src\libvirt-java\src\main\java\org\libvirt\Connect.java:658: warning - @return tag has no arguments. [javadoc] x:\src\libvirt-java\src\main\java\org\libvirt\Domain.java:681: warning - @return tag has no arguments. [javadoc] x:\src\libvirt-java\src\main\java\org\libvirt\Domain.java:795: warning - Tag @see: reference not found: http [javadoc] ://www.libvirt.org/html/libvirt-libvirt.html#virDomainMigrateToURI [javadoc] x:\src\libvirt-java\src\main\java\org\libvirt\DomainSnapshot.java:40: warning - @return tag has no arguments. [javadoc] x:\src\libvirt-java\src\main\java\org\libvirt\StoragePool.java:349: warning - @return tag has no arguments. [javadoc] x:\src\libvirt-java\src\main\java\org\libvirt\Stream.java:130: warning - Tag @see:illegal character: "58" in "http://www.libvirt.org/html/libvi rt-libvirt.html#virStreamRecvAll" [javadoc] x:\src\libvirt-java\src\main\java\org\libvirt\Stream.java:130: warning - Tag @see:illegal character: "47" in "http://www.libvirt.org/html/libvi rt-libvirt.html#virStreamRecvAll" [javadoc] x:\src\libvirt-java\src\main\java\org\libvirt\Stream.java:130: warning - Tag @see:illegal character: "47" in "http://www.libvirt.org/html/libvi rt-libvirt.html#virStreamRecvAll" [javadoc] x:\src\libvirt-java\src\main\java\org\libvirt\Stream.java:130: warning - Tag @see:illegal character: "47" in "http://www.libvirt.org/html/libvi rt-libvirt.html#virStreamRecvAll" [javadoc] x:\src\libvirt-java\src\main\java\org\libvirt\Stream.java:130: warning - Tag @see:illegal character: "47" in "http://www.libvirt.org/html/libvi rt-libvirt.html#virStreamRecvAll" [javadoc] x:\src\libvirt-java\src\main\java\org\libvirt\Stream.java:130: warning - Tag @see:illegal character: "45" in "http://www.libvirt.org/html/libvi rt-libvirt.html#virStreamRecvAll" [javadoc] x:\src\libvirt-java\src\main\java\org\libvirt\Stream.java:130: warning - Tag @see: reference not found: http://www.libvirt.org/html/libvirt-lib virt.html#virStreamRecvAll ---
--- diff --git a/src/main/java/org/libvirt/Connect.java b/src/main/java/org/libvirt/Connect.java index 77336f0..de75f20 100644 --- a/src/main/java/org/libvirt/Connect.java +++ b/src/main/java/org/libvirt/Connect.java @@ -381,7 +381,7 @@ public class Connect { * Documentation</a> * @param callbackID * the callback to deregister - * @return + * @return 0 on success, -1 on failure * @throws LibvirtException */ public int domainEventDeregister(int callbackID) throws LibvirtException { @@ -400,7 +400,7 @@ public class Connect { int action); }
- private interface GenericCallback { + protected interface GenericCallback { void eventCallback(Connect connect, Domain domain); } public interface RebootCallback extends GenericCallback { @@ -638,7 +638,7 @@ public class Connect { * domain configuration file describing the domain. The format of the native * data is hypervisor dependant. * - * @return + * @return domain XML as String, or {@code null} on error * @throws LibvirtException */ public String domainXMLFromNative(String nativeFormat, String nativeConfig, int flags) throws LibvirtException { @@ -652,7 +652,7 @@ public class Connect { * native configuration file describing the domain. The format of the native * data is hypervisor dependant. * - * @return + * @return domain XML as String, or {@code null} on error * @throws LibvirtException */ public String domainXMLToNative(String nativeFormat, String domainXML, int flags) throws LibvirtException { diff --git a/src/main/java/org/libvirt/Domain.java b/src/main/java/org/libvirt/Domain.java index fd7a03a..fe9f3b0 100644 --- a/src/main/java/org/libvirt/Domain.java +++ b/src/main/java/org/libvirt/Domain.java @@ -675,7 +675,7 @@ public class Domain { * @see <a * href="http://www.libvirt.org/html/libvirt-libvirt.html#virDomainManagedSaveRemove">Libvirt * Documentation</a> - * @return + * @return 0 in case of success, and -1 in case of error * @throws LibvirtException */ public int managedSaveRemote() throws LibvirtException { @@ -778,8 +778,9 @@ public class Domain { * Migrate the domain object from its current host to the destination host * given by duri. * - * @see http - * ://www.libvirt.org/html/libvirt-libvirt.html#virDomainMigrateToURI + * @see <a + * href="http://www.libvirt.org/html/libvirt-libvirt.html#virDomainMigrateToURI"> + * virDomainMigrateToURI</a> * * @param uri * The destination URI diff --git a/src/main/java/org/libvirt/DomainSnapshot.java b/src/main/java/org/libvirt/DomainSnapshot.java index e9a23d6..add6830 100644 --- a/src/main/java/org/libvirt/DomainSnapshot.java +++ b/src/main/java/org/libvirt/DomainSnapshot.java @@ -34,7 +34,7 @@ public class DomainSnapshot { * Documentation</a> * @param flags * controls teh deletion - * @return + * @return 0 if the selected snapshot(s) were successfully deleted, -1 on error. * @throws LibvirtException */ public int delete(int flags) throws LibvirtException { diff --git a/src/main/java/org/libvirt/StoragePool.java b/src/main/java/org/libvirt/StoragePool.java index a3d59a9..0328d8c 100644 --- a/src/main/java/org/libvirt/StoragePool.java +++ b/src/main/java/org/libvirt/StoragePool.java @@ -343,7 +343,7 @@ public class StoragePool { * as input. Information for the new volume (name, perms) are passed via a * typical volume XML description. * - * @return + * @return The storage volume, or {@code null} on error. * @throws LibvirtException */ public StorageVol storageVolCreateXMLFrom(String xmlDesc, StorageVol cloneVolume, int flags) diff --git a/src/main/java/org/libvirt/Stream.java b/src/main/java/org/libvirt/Stream.java index fdef3a4..6374567 100644 --- a/src/main/java/org/libvirt/Stream.java +++ b/src/main/java/org/libvirt/Stream.java @@ -121,7 +121,7 @@ public class Stream { /** * Batch receive method * - * @see http://www.libvirt.org/html/libvirt-libvirt.html#virStreamRecvAll + * @see <a href="http://www.libvirt.org/html/libvirt-libvirt.html#virStreamRecvAll">virStreamRecvAll</a> * @param handler * the callback handler * @return 0 if successfule, -1 otherwise
---
-- AV-Test GmbH, Henricistraße 20, 04155 Leipzig, Germany Phone: +49 341 265 310 19 Web:<http://www.av-test.org> Eingetragen am / Registered at: Amtsgericht Stendal (HRB 114076) Geschaeftsfuehrer (CEO): Andreas Marx, Guido Habicht, Maik Morgenstern
On 07/19/2012 06:31 AM, Claudio Bley wrote:
ping... ?!
Isn't this the appropriate list? What's the status of libvirt-java?
This is the right list. Unfortunately, at the moment libvirt-java does not have an active maintainer; there have been several patches proposed lately by various individuals, and they are slowly getting applied as people have time, but there's a lot more work to be done to catch libvirt-java up to being an accurate binding to the latest C interface. Submit enough patches and you can earn the commit rights to become such a maintainer, and get these patches reviewed with less delay :) Personally, it's been years since I've written in Java, so I have kind of shied away from reviewing libvirt-java patches, so I'm probably not helping the situation of libvirt-java being out of date. But this particular patch is easy to review - no code changes, just doc fixes, so I would be inclined to push it if it didn't take more than 2 minutes of my time.
At Mon, 09 Jul 2012 10:23:42 +0200, Claudio Bley wrote:
Here's a patch fixing these javadoc warnings:
--- [javadoc] x:\src\libvirt-java\src\main\java\org\libvirt\Connect.java:387: warning - @return tag has no arguments.
Your patch looks reasonable, but it was not in a format that 'git am' recognizes. Can you re-submit as a formal patch using 'git send-email', to make it easier for maintainers to apply your patch without massaging it first? -- Eric Blake eblake@redhat.com +1-919-301-3266 Libvirt virtualization library http://libvirt.org
At Thu, 19 Jul 2012 07:45:00 -0600, Eric Blake wrote:
On 07/19/2012 06:31 AM, Claudio Bley wrote:
ping... ?!
Isn't this the appropriate list? What's the status of libvirt-java?
This is the right list. Unfortunately, at the moment libvirt-java does not have an active maintainer
OK, this was my faint suspicion; looking at the code / trying to use it.
there have been several patches proposed lately by various individuals, and they are slowly getting applied as people have time, but there's a lot more work to be done to catch libvirt-java up to being an accurate binding to the latest C interface.
I still have a few improvements on my list.
Submit enough patches and you can earn the commit rights to become such a maintainer, and get these patches reviewed with less delay :)
Fair enough. :)
Your patch looks reasonable, but it was not in a format that 'git am' recognizes. Can you re-submit as a formal patch using 'git send-email', to make it easier for maintainers to apply your patch without massaging it first?
Sure thing. Here you are... -- >8 -- Subject: [PATCH] Fix javadoc warnings. This affects comments only. --- src/main/java/org/libvirt/Connect.java | 6 +++--- src/main/java/org/libvirt/Domain.java | 7 ++++--- src/main/java/org/libvirt/DomainSnapshot.java | 2 +- src/main/java/org/libvirt/StoragePool.java | 2 +- src/main/java/org/libvirt/Stream.java | 2 +- 5 files changed, 10 insertions(+), 9 deletions(-) diff --git a/src/main/java/org/libvirt/Connect.java b/src/main/java/org/libvirt/Connect.java index 4cff0cb..0a94976 100644 --- a/src/main/java/org/libvirt/Connect.java +++ b/src/main/java/org/libvirt/Connect.java @@ -383,7 +383,7 @@ public class Connect { * Documentation</a> * @param callbackID * the callback to deregister - * @return + * @return 0 on success, -1 on failure * @throws LibvirtException */ public int domainEventDeregisterAny(int callbackID) throws LibvirtException { @@ -509,7 +509,7 @@ public class Connect { * domain configuration file describing the domain. The format of the native * data is hypervisor dependant. * - * @return + * @return domain XML as String, or {@code null} on error * @throws LibvirtException */ public String domainXMLFromNative(String nativeFormat, String nativeConfig, int flags) throws LibvirtException { @@ -523,7 +523,7 @@ public class Connect { * native configuration file describing the domain. The format of the native * data is hypervisor dependant. * - * @return + * @return domain XML as String, or {@code null} on error * @throws LibvirtException */ public String domainXMLToNative(String nativeFormat, String domainXML, int flags) throws LibvirtException { diff --git a/src/main/java/org/libvirt/Domain.java b/src/main/java/org/libvirt/Domain.java index d534709..1f15ee8 100644 --- a/src/main/java/org/libvirt/Domain.java +++ b/src/main/java/org/libvirt/Domain.java @@ -675,7 +675,7 @@ public class Domain { * @see <a * href="http://www.libvirt.org/html/libvirt-libvirt.html#virDomainManagedSaveRemove">Libvirt * Documentation</a> - * @return + * @return 0 in case of success, and -1 in case of error * @throws LibvirtException */ public int managedSaveRemove() throws LibvirtException { @@ -778,8 +778,9 @@ public class Domain { * Migrate the domain object from its current host to the destination host * given by duri. * - * @see http - * ://www.libvirt.org/html/libvirt-libvirt.html#virDomainMigrateToURI + * @see <a + * href="http://www.libvirt.org/html/libvirt-libvirt.html#virDomainMigrateToURI"> + * virDomainMigrateToURI</a> * * @param uri * The destination URI diff --git a/src/main/java/org/libvirt/DomainSnapshot.java b/src/main/java/org/libvirt/DomainSnapshot.java index e9a23d6..add6830 100644 --- a/src/main/java/org/libvirt/DomainSnapshot.java +++ b/src/main/java/org/libvirt/DomainSnapshot.java @@ -34,7 +34,7 @@ public class DomainSnapshot { * Documentation</a> * @param flags * controls teh deletion - * @return + * @return 0 if the selected snapshot(s) were successfully deleted, -1 on error. * @throws LibvirtException */ public int delete(int flags) throws LibvirtException { diff --git a/src/main/java/org/libvirt/StoragePool.java b/src/main/java/org/libvirt/StoragePool.java index a3d59a9..0328d8c 100644 --- a/src/main/java/org/libvirt/StoragePool.java +++ b/src/main/java/org/libvirt/StoragePool.java @@ -343,7 +343,7 @@ public class StoragePool { * as input. Information for the new volume (name, perms) are passed via a * typical volume XML description. * - * @return + * @return The storage volume, or {@code null} on error. * @throws LibvirtException */ public StorageVol storageVolCreateXMLFrom(String xmlDesc, StorageVol cloneVolume, int flags) diff --git a/src/main/java/org/libvirt/Stream.java b/src/main/java/org/libvirt/Stream.java index fdef3a4..6374567 100644 --- a/src/main/java/org/libvirt/Stream.java +++ b/src/main/java/org/libvirt/Stream.java @@ -121,7 +121,7 @@ public class Stream { /** * Batch receive method * - * @see http://www.libvirt.org/html/libvirt-libvirt.html#virStreamRecvAll + * @see <a href="http://www.libvirt.org/html/libvirt-libvirt.html#virStreamRecvAll">virStreamRecvAll</a> * @param handler * the callback handler * @return 0 if successfule, -1 otherwise -- 1.7.11.msysgit.0 -- AV-Test GmbH, Henricistraße 20, 04155 Leipzig, Germany Phone: +49 341 265 310 19 Web:<http://www.av-test.org> Eingetragen am / Registered at: Amtsgericht Stendal (HRB 114076) Geschaeftsfuehrer (CEO): Andreas Marx, Guido Habicht, Maik Morgenstern
On 07/23/2012 04:12 AM, Claudio Bley wrote:
Your patch looks reasonable, but it was not in a format that 'git am' recognizes. Can you re-submit as a formal patch using 'git send-email', to make it easier for maintainers to apply your patch without massaging it first?
Sure thing. Here you are...
-- >8 -- Subject: [PATCH] Fix javadoc warnings.
This affects comments only.
Thanks; pushed. -- Eric Blake eblake@redhat.com +1-919-301-3266 Libvirt virtualization library http://libvirt.org
participants (2)
-
Claudio Bley -
Eric Blake