Libguestfs - Mar 2017 - [PATCH] generator: java: Don't link to undocumented methods.

We aren't generating Java bindings for internal and other undocumented
methods, and therefore providing {@link #...}  for deprecated methods
replaced by internal methods doesn't work.  The easiest way is just to
check for this and turn such links into plain text.
---
 generator/java.ml | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/generator/java.ml b/generator/java.ml
index 83f2e65..732cbe6 100644
--- a/generator/java.ml
+++ b/generator/java.ml
@@ -299,7 +299,15 @@ public class GuestFS {
         (match f with
         | { deprecated_by = Not_deprecated } -> ()
         | { deprecated_by = Replaced_by alt } ->
-          pr "   * @deprecated In new code, use {@link #%s}
instead\n" alt
+          (* Don't link to an undocumented function as javadoc will
+           * give a hard error.
+           *)
+          let f_alt = try List.find (fun { name = n } -> n = alt) actions
+                      with Not_found -> assert false in
+          if is_documented f_alt then
+            pr "   * @deprecated In new code, use {@link #%s}
instead\n" alt
+          else
+            pr "   * @deprecated In new code, use method %s
instead\n" alt
         | { deprecated_by = Deprecated_no_replacement } ->
           pr "   * @deprecated\n"
         );
-- 
2.9.3

On Friday, 3 March 2017 11:18:39 CET Richard W.M. Jones
wrote:
> We aren't generating Java bindings for internal and other undocumented
> methods, and therefore providing {@link #...}  for deprecated methods
> replaced by internal methods doesn't work.  The easiest way is just to
> check for this and turn such links into plain text.
> ---
Wouldn't it better just put a "deprecated, don't use" text
instead,
without even mentioning a method that is not available in the bindings?

Thanks,
-- 
Pino Toscano

On Fri, Mar 03, 2017 at 04:35:22PM +0100, Pino Toscano
wrote:
> On Friday, 3 March 2017 11:18:39 CET Richard W.M. Jones wrote:
> > We aren't generating Java bindings for internal and other
undocumented
> > methods, and therefore providing {@link #...}  for deprecated methods
> > replaced by internal methods doesn't work.  The easiest way is
just to
> > check for this and turn such links into plain text.
> > ---
> 
> Wouldn't it better just put a "deprecated, don't use"
text instead,
> without even mentioning a method that is not available in the bindings?
Sure, I'll change it as you say and push.

Thanks,
Rich.

-- 
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
Read my programming and virtualization blog: http://rwmj.wordpress.com
virt-p2v converts physical machines to virtual machines.  Boot with a
live CD or over the network (PXE) and turn machines into KVM guests.
http://libguestfs.org/virt-v2v