From: Gerhard Sittig <redacted>
Date: Sat, 25 Dec 2021 18:43:48 +0000 (+0100)
Subject: type_decoder: move Python doc strings to method implementations
X-Git-Url: https://sigrok.org/gitaction?a=commitdiff_plain;h=e4bea07dd4e58b1b1becdcc5df6aa6fe33205c65;p=libsigrokdecode.git

type_decoder: move Python doc strings to method implementations

Move Python doc strings to the location where methods and classes get
implemented. This improves awareness during maintenance, and allows for
longer text phrases without obfuscating the registration code path.

This commit does not alter the content of existing doc strings, only
moves their location. And keeps related items together when long decls
span multiple text lines (function name and arguments list, args and
kw args), to improve/keep readability.
---

diff --git a/type_decoder.c b/type_decoder.c
index b57b606..67cdbb2 100644
--- a/type_decoder.c
+++ b/type_decoder.c
@@ -396,6 +396,10 @@ static void release_meta(GVariant *gvar)
 	g_variant_unref(gvar);
 }
 
+PyDoc_STRVAR(Decoder_put_doc,
+	"Accepts a dictionary with the following keys: startsample, endsample, data"
+);
+
 static PyObject *Decoder_put(PyObject *self, PyObject *args)
 {
 	GSList *l;
@@ -554,8 +558,12 @@ err:
 	return NULL;
 }
 
-static PyObject *Decoder_register(PyObject *self, PyObject *args,
-		PyObject *kwargs)
+PyDoc_STRVAR(Decoder_register_doc,
+	"Register a new output stream"
+);
+
+static PyObject *Decoder_register(PyObject *self,
+	PyObject *args, PyObject *kwargs)
 {
 	struct srd_decoder_inst *di;
 	struct srd_pd_output *pdo;
@@ -952,6 +960,10 @@ static int set_skip_condition(struct srd_decoder_inst *di, uint64_t count)
 	return SRD_OK;
 }
 
+PyDoc_STRVAR(Decoder_wait_doc,
+	"Wait for one or more conditions to occur"
+);
+
 static PyObject *Decoder_wait(PyObject *self, PyObject *args)
 {
 	int ret;
@@ -1085,6 +1097,10 @@ err:
 	return NULL;
 }
 
+PyDoc_STRVAR(Decoder_has_channel_doc,
+	"Report whether a channel was supplied"
+);
+
 /**
  * Return whether the specified channel was supplied to the decoder.
  *
@@ -1141,15 +1157,25 @@ err:
 	return NULL;
 }
 
+PyDoc_STRVAR(Decoder_doc, "sigrok Decoder base class");
+
 static PyMethodDef Decoder_methods[] = {
-	{ "put", Decoder_put, METH_VARARGS,
-	  "Accepts a dictionary with the following keys: startsample, endsample, data" },
-	{ "register", (PyCFunction)(void(*)(void))Decoder_register, METH_VARARGS|METH_KEYWORDS,
-			"Register a new output stream" },
-	{ "wait", Decoder_wait, METH_VARARGS,
-			"Wait for one or more conditions to occur" },
-	{ "has_channel", Decoder_has_channel, METH_VARARGS,
-			"Report whether a channel was supplied" },
+	{ "put",
+	  Decoder_put, METH_VARARGS,
+	  Decoder_put_doc,
+	},
+	{ "register",
+	  (PyCFunction)(void(*)(void))Decoder_register, METH_VARARGS | METH_KEYWORDS,
+	  Decoder_register_doc,
+	},
+	{ "wait",
+	  Decoder_wait, METH_VARARGS,
+	  Decoder_wait_doc,
+	},
+	{ "has_channel",
+	  Decoder_has_channel, METH_VARARGS,
+	  Decoder_has_channel_doc,
+	},
 	{NULL, NULL, 0, NULL}
 };
 
@@ -1164,7 +1190,7 @@ SRD_PRIV PyObject *srd_Decoder_type_new(void)
 {
 	PyType_Spec spec;
 	PyType_Slot slots[] = {
-		{ Py_tp_doc, "sigrok Decoder base class" },
+		{ Py_tp_doc, Decoder_doc },
 		{ Py_tp_methods, Decoder_methods },
 		{ Py_tp_new, (void *)&PyType_GenericNew },
 		{ 0, NULL }