swig/python: add minimal documentation

uses autodoc to display the function arguments rather than the
inscrutable va_args (*args).

Change-Id: Iec2ff8276c1533b14c3032836d822fbdae632521
(cherry picked from commit 825b64db53368f18f4546f99c04d1af5c558613e)

3 files changed, 59 insertions, 32 deletions

diff --git a/swig/libwebp.i b/swig/libwebp.i
index 20977c77..5e887184 100644
--- a/swig/libwebp.i
+++ b/swig/libwebp.i
@@ -75,6 +75,18 @@ JAVA_ARRAYS_TYPEMAPS(uint8_t, byte, jbyte, Uint8, "[B")
 %typemap(freearg) const uint8_t* rgb {
   PyBuffer_Release(&rgb_buffer$argnum);
 }
+
+%define DECODE_AUTODOC(func)
+%feature("autodoc", #func "(uint8_t data) -> (rgb, width, height)") func;
+%enddef
+
+%feature("autodoc", "1");
+DECODE_AUTODOC(WebPDecodeRGB);
+DECODE_AUTODOC(WebPDecodeRGBA);
+DECODE_AUTODOC(WebPDecodeARGB);
+DECODE_AUTODOC(WebPDecodeBGR);
+DECODE_AUTODOC(WebPDecodeBGRA);
+%feature("autodoc", "WebPGetInfo(uint8_t data) -> (width, height)") WebPGetInfo;
 #endif  /* SWIGPYTHON */
 
 //------------------------------------------------------------------------------
@@ -247,6 +259,11 @@ static uint8_t* EncodeLossless(const uint8_t* rgb,
 %javamethodmodifiers wrap_WebPEncodeLosslessBGRA "private";
 #endif  /* SWIGJAVA */
 
+#ifdef SWIGPYTHON
+// This autodoc will serve as a catch-all for wrap_*.
+%feature("autodoc", "private, do not call directly.");
+#endif
+
 %inline %{
 // Changes the return type of WebPEncode* to more closely match Decode*.
 // This also makes it easier to wrap the output buffer in a native type rather
@@ -343,6 +360,7 @@ _UNUSED = 1
 %define CALL_ENCODE_LOSSY_WRAPPER(func)
 %pythoncode %{
 def func(rgb, width, height, stride, quality_factor):
+  """func(uint8_t rgb, int width, int height, int stride, float quality_factor) -> lossy_webp"""
   webp = wrap_##func(
       rgb, _UNUSED, _UNUSED, width, height, stride, quality_factor)
   if len(webp[0]) == 0:
@@ -354,6 +372,7 @@ def func(rgb, width, height, stride, quality_factor):
 %define CALL_ENCODE_LOSSLESS_WRAPPER(func)
 %pythoncode %{
 def func(rgb, width, height, stride):
+  """func(uint8_t rgb, int width, int height, int stride) -> lossless_webp"""
   webp = wrap_##func(rgb, _UNUSED, _UNUSED, width, height, stride)
   if len(webp[0]) == 0:
     return None
diff --git a/swig/libwebp.py b/swig/libwebp.py
index 31ad4d5b..4ff11f80 100644
--- a/swig/libwebp.py
+++ b/swig/libwebp.py
@@ -69,71 +69,72 @@ except AttributeError:
 
 
 def WebPGetDecoderVersion():
+  """WebPGetDecoderVersion() -> int"""
   return _libwebp.WebPGetDecoderVersion()
-WebPGetDecoderVersion = _libwebp.WebPGetDecoderVersion
 
 def WebPGetInfo(*args):
+  """WebPGetInfo(uint8_t data) -> (width, height)"""
   return _libwebp.WebPGetInfo(*args)
-WebPGetInfo = _libwebp.WebPGetInfo
 
 def WebPDecodeRGB(*args):
+  """WebPDecodeRGB(uint8_t data) -> (rgb, width, height)"""
   return _libwebp.WebPDecodeRGB(*args)
-WebPDecodeRGB = _libwebp.WebPDecodeRGB
 
 def WebPDecodeRGBA(*args):
+  """WebPDecodeRGBA(uint8_t data) -> (rgb, width, height)"""
   return _libwebp.WebPDecodeRGBA(*args)
-WebPDecodeRGBA = _libwebp.WebPDecodeRGBA
 
 def WebPDecodeARGB(*args):
+  """WebPDecodeARGB(uint8_t data) -> (rgb, width, height)"""
   return _libwebp.WebPDecodeARGB(*args)
-WebPDecodeARGB = _libwebp.WebPDecodeARGB
 
 def WebPDecodeBGR(*args):
+  """WebPDecodeBGR(uint8_t data) -> (rgb, width, height)"""
   return _libwebp.WebPDecodeBGR(*args)
-WebPDecodeBGR = _libwebp.WebPDecodeBGR
 
 def WebPDecodeBGRA(*args):
+  """WebPDecodeBGRA(uint8_t data) -> (rgb, width, height)"""
   return _libwebp.WebPDecodeBGRA(*args)
-WebPDecodeBGRA = _libwebp.WebPDecodeBGRA
 
 def WebPGetEncoderVersion():
+  """WebPGetEncoderVersion() -> int"""
   return _libwebp.WebPGetEncoderVersion()
-WebPGetEncoderVersion = _libwebp.WebPGetEncoderVersion
 
 def wrap_WebPEncodeRGB(*args):
+  """private, do not call directly."""
   return _libwebp.wrap_WebPEncodeRGB(*args)
-wrap_WebPEncodeRGB = _libwebp.wrap_WebPEncodeRGB
 
 def wrap_WebPEncodeBGR(*args):
+  """private, do not call directly."""
   return _libwebp.wrap_WebPEncodeBGR(*args)
-wrap_WebPEncodeBGR = _libwebp.wrap_WebPEncodeBGR
 
 def wrap_WebPEncodeRGBA(*args):
+  """private, do not call directly."""
   return _libwebp.wrap_WebPEncodeRGBA(*args)
-wrap_WebPEncodeRGBA = _libwebp.wrap_WebPEncodeRGBA
 
 def wrap_WebPEncodeBGRA(*args):
+  """private, do not call directly."""
   return _libwebp.wrap_WebPEncodeBGRA(*args)
-wrap_WebPEncodeBGRA = _libwebp.wrap_WebPEncodeBGRA
 
 def wrap_WebPEncodeLosslessRGB(*args):
+  """private, do not call directly."""
   return _libwebp.wrap_WebPEncodeLosslessRGB(*args)
-wrap_WebPEncodeLosslessRGB = _libwebp.wrap_WebPEncodeLosslessRGB
 
 def wrap_WebPEncodeLosslessBGR(*args):
+  """private, do not call directly."""
   return _libwebp.wrap_WebPEncodeLosslessBGR(*args)
-wrap_WebPEncodeLosslessBGR = _libwebp.wrap_WebPEncodeLosslessBGR
 
 def wrap_WebPEncodeLosslessRGBA(*args):
+  """private, do not call directly."""
   return _libwebp.wrap_WebPEncodeLosslessRGBA(*args)
-wrap_WebPEncodeLosslessRGBA = _libwebp.wrap_WebPEncodeLosslessRGBA
 
 def wrap_WebPEncodeLosslessBGRA(*args):
+  """private, do not call directly."""
   return _libwebp.wrap_WebPEncodeLosslessBGRA(*args)
-wrap_WebPEncodeLosslessBGRA = _libwebp.wrap_WebPEncodeLosslessBGRA
 _UNUSED = 1
 
 def WebPEncodeRGB(rgb, width, height, stride, quality_factor):
+  """WebPEncodeRGB(uint8_t rgb, int width, int height, int stride, float quality_factor) -> lossy_webp"""
   webp = wrap_WebPEncodeRGB(
       rgb, _UNUSED, _UNUSED, width, height, stride, quality_factor)
   if len(webp[0]) == 0:
@@ -141,6 +142,7 @@ def WebPEncodeRGB(rgb, width, height, stride, quality_factor):
   return webp[0]
 
 def WebPEncodeRGBA(rgb, width, height, stride, quality_factor):
+  """WebPEncodeRGBA(uint8_t rgb, int width, int height, int stride, float quality_factor) -> lossy_webp"""
   webp = wrap_WebPEncodeRGBA(
       rgb, _UNUSED, _UNUSED, width, height, stride, quality_factor)
   if len(webp[0]) == 0:
@@ -148,6 +150,7 @@ def WebPEncodeRGBA(rgb, width, height, stride, quality_factor):
   return webp[0]
 
 def WebPEncodeBGR(rgb, width, height, stride, quality_factor):
+  """WebPEncodeBGR(uint8_t rgb, int width, int height, int stride, float quality_factor) -> lossy_webp"""
   webp = wrap_WebPEncodeBGR(
       rgb, _UNUSED, _UNUSED, width, height, stride, quality_factor)
   if len(webp[0]) == 0:
@@ -155,6 +158,7 @@ def WebPEncodeBGR(rgb, width, height, stride, quality_factor):
   return webp[0]
 
 def WebPEncodeBGRA(rgb, width, height, stride, quality_factor):
+  """WebPEncodeBGRA(uint8_t rgb, int width, int height, int stride, float quality_factor) -> lossy_webp"""
   webp = wrap_WebPEncodeBGRA(
       rgb, _UNUSED, _UNUSED, width, height, stride, quality_factor)
   if len(webp[0]) == 0:
@@ -162,24 +166,28 @@ def WebPEncodeBGRA(rgb, width, height, stride, quality_factor):
   return webp[0]
 
 def WebPEncodeLosslessRGB(rgb, width, height, stride):
+  """WebPEncodeLosslessRGB(uint8_t rgb, int width, int height, int stride) -> lossless_webp"""
   webp = wrap_WebPEncodeLosslessRGB(rgb, _UNUSED, _UNUSED, width, height, stride)
   if len(webp[0]) == 0:
     return None
   return webp[0]
 
 def WebPEncodeLosslessRGBA(rgb, width, height, stride):
+  """WebPEncodeLosslessRGBA(uint8_t rgb, int width, int height, int stride) -> lossless_webp"""
   webp = wrap_WebPEncodeLosslessRGBA(rgb, _UNUSED, _UNUSED, width, height, stride)
   if len(webp[0]) == 0:
     return None
   return webp[0]
 
 def WebPEncodeLosslessBGR(rgb, width, height, stride):
+  """WebPEncodeLosslessBGR(uint8_t rgb, int width, int height, int stride) -> lossless_webp"""
   webp = wrap_WebPEncodeLosslessBGR(rgb, _UNUSED, _UNUSED, width, height, stride)
   if len(webp[0]) == 0:
     return None
   return webp[0]
 
 def WebPEncodeLosslessBGRA(rgb, width, height, stride):
+  """WebPEncodeLosslessBGRA(uint8_t rgb, int width, int height, int stride) -> lossless_webp"""
   webp = wrap_WebPEncodeLosslessBGRA(rgb, _UNUSED, _UNUSED, width, height, stride)
   if len(webp[0]) == 0:
     return None
diff --git a/swig/libwebp_python_wrap.c b/swig/libwebp_python_wrap.c
index 5e8e89ca..b29f8349 100644
--- a/swig/libwebp_python_wrap.c
+++ b/swig/libwebp_python_wrap.c
@@ -4664,22 +4664,22 @@ fail:
 
 static PyMethodDef SwigMethods[] = {
          { (char *)"SWIG_PyInstanceMethod_New", (PyCFunction)SWIG_PyInstanceMethod_New, METH_O, NULL},
-         { (char *)"WebPGetDecoderVersion", _wrap_WebPGetDecoderVersion, METH_VARARGS, NULL},
-         { (char *)"WebPGetInfo", _wrap_WebPGetInfo, METH_VARARGS, NULL},
-         { (char *)"WebPDecodeRGB", _wrap_WebPDecodeRGB, METH_VARARGS, NULL},
-         { (char *)"WebPDecodeRGBA", _wrap_WebPDecodeRGBA, METH_VARARGS, NULL},
-         { (char *)"WebPDecodeARGB", _wrap_WebPDecodeARGB, METH_VARARGS, NULL},
-         { (char *)"WebPDecodeBGR", _wrap_WebPDecodeBGR, METH_VARARGS, NULL},
-         { (char *)"WebPDecodeBGRA", _wrap_WebPDecodeBGRA, METH_VARARGS, NULL},
-         { (char *)"WebPGetEncoderVersion", _wrap_WebPGetEncoderVersion, METH_VARARGS, NULL},
-         { (char *)"wrap_WebPEncodeRGB", _wrap_wrap_WebPEncodeRGB, METH_VARARGS, NULL},
-         { (char *)"wrap_WebPEncodeBGR", _wrap_wrap_WebPEncodeBGR, METH_VARARGS, NULL},
-         { (char *)"wrap_WebPEncodeRGBA", _wrap_wrap_WebPEncodeRGBA, METH_VARARGS, NULL},
-         { (char *)"wrap_WebPEncodeBGRA", _wrap_wrap_WebPEncodeBGRA, METH_VARARGS, NULL},
-         { (char *)"wrap_WebPEncodeLosslessRGB", _wrap_wrap_WebPEncodeLosslessRGB, METH_VARARGS, NULL},
-         { (char *)"wrap_WebPEncodeLosslessBGR", _wrap_wrap_WebPEncodeLosslessBGR, METH_VARARGS, NULL},
-         { (char *)"wrap_WebPEncodeLosslessRGBA", _wrap_wrap_WebPEncodeLosslessRGBA, METH_VARARGS, NULL},
-         { (char *)"wrap_WebPEncodeLosslessBGRA", _wrap_wrap_WebPEncodeLosslessBGRA, METH_VARARGS, NULL},
+         { (char *)"WebPGetDecoderVersion", _wrap_WebPGetDecoderVersion, METH_VARARGS, (char *)"WebPGetDecoderVersion() -> int"},
+         { (char *)"WebPGetInfo", _wrap_WebPGetInfo, METH_VARARGS, (char *)"WebPGetInfo(uint8_t data) -> (width, height)"},
+         { (char *)"WebPDecodeRGB", _wrap_WebPDecodeRGB, METH_VARARGS, (char *)"WebPDecodeRGB(uint8_t data) -> (rgb, width, height)"},
+         { (char *)"WebPDecodeRGBA", _wrap_WebPDecodeRGBA, METH_VARARGS, (char *)"WebPDecodeRGBA(uint8_t data) -> (rgb, width, height)"},
+         { (char *)"WebPDecodeARGB", _wrap_WebPDecodeARGB, METH_VARARGS, (char *)"WebPDecodeARGB(uint8_t data) -> (rgb, width, height)"},
+         { (char *)"WebPDecodeBGR", _wrap_WebPDecodeBGR, METH_VARARGS, (char *)"WebPDecodeBGR(uint8_t data) -> (rgb, width, height)"},
+         { (char *)"WebPDecodeBGRA", _wrap_WebPDecodeBGRA, METH_VARARGS, (char *)"WebPDecodeBGRA(uint8_t data) -> (rgb, width, height)"},
+         { (char *)"WebPGetEncoderVersion", _wrap_WebPGetEncoderVersion, METH_VARARGS, (char *)"WebPGetEncoderVersion() -> int"},
+         { (char *)"wrap_WebPEncodeRGB", _wrap_wrap_WebPEncodeRGB, METH_VARARGS, (char *)"private, do not call directly."},
+         { (char *)"wrap_WebPEncodeBGR", _wrap_wrap_WebPEncodeBGR, METH_VARARGS, (char *)"private, do not call directly."},
+         { (char *)"wrap_WebPEncodeRGBA", _wrap_wrap_WebPEncodeRGBA, METH_VARARGS, (char *)"private, do not call directly."},
+         { (char *)"wrap_WebPEncodeBGRA", _wrap_wrap_WebPEncodeBGRA, METH_VARARGS, (char *)"private, do not call directly."},
+         { (char *)"wrap_WebPEncodeLosslessRGB", _wrap_wrap_WebPEncodeLosslessRGB, METH_VARARGS, (char *)"private, do not call directly."},
+         { (char *)"wrap_WebPEncodeLosslessBGR", _wrap_wrap_WebPEncodeLosslessBGR, METH_VARARGS, (char *)"private, do not call directly."},
+         { (char *)"wrap_WebPEncodeLosslessRGBA", _wrap_wrap_WebPEncodeLosslessRGBA, METH_VARARGS, (char *)"private, do not call directly."},
+         { (char *)"wrap_WebPEncodeLosslessBGRA", _wrap_wrap_WebPEncodeLosslessBGRA, METH_VARARGS, (char *)"private, do not call directly."},
          { NULL, NULL, 0, NULL }
 };