Enhancement in method declaration

Write a macro allowing to "declare" method header's argument list

config.h

@@ -18,5 +18,15 @@
  */
 #ifndef __RPN_CONFIG__
 #define __RPN_CONFIG__
+
 #define _GNU_SOURCE
+
+
+#define PYRPN_doc_meth(NAME, header, docstring) PyDoc_STRVAR(NAME ## _doc,\
+		header "\n--\n\n" docstring);
+
+#define PYRPN_method(name, callback, flags, header, docstring) \
+{name, (PyCFunction)callback, flags, \
+	PyDoc_STR(name "("header ")\n--\n\n" docstring)}
+
 #endif

python_if.c

@@ -1,43 +1,57 @@
 #include "python_if.h"
 
-PyMethodDef RPNIterExpr_methods[] = {
-	{"get_params", (PyCFunction)rpnif_get_params, METH_NOARGS,
-		"Get a named tuple with parameters"},
-	{"keys", (PyCFunction)rpnif_keys, METH_NOARGS,
-		"Get the list of keys identifing the expressions"},
-	{"values", (PyCFunction)rpnif_values, METH_NOARGS,
-		"Get the list of expressions"},
-	{"items", (PyCFunction)rpnif_items, METH_NOARGS,
-		"Iterate on couple of (key, expr)"},
-	{"step", (PyCFunction)rpnif_step, METH_O,
-		"Run an IF given a position and return the new position"},
-	{"__getstate__", (PyCFunction)rpnif_getstate, METH_NOARGS,
-		"Pickling method. Return a bytes repr of tokenized expression \
-and the stack state."},
-	{"__setstate__", (PyCFunction)rpnif_setstate, METH_O,
-		"Unpickling method"},
+static PyMethodDef RPNIterExpr_methods[] = {
+	PYRPN_method("get_params", rpnif_get_params,
+			METH_NOARGS,
+			"self, /",
+			"Get a name tuple with parameters"),
+	PYRPN_method("keys", rpnif_keys,
+			METH_NOARGS,
+			"self, /",
+			"Return items keys (see dict.keys)"),
+	PYRPN_method("values", rpnif_values,
+			METH_NOARGS,
+			"self, /",
+			"Return items values (see dict.values)"),
+	PYRPN_method("items", rpnif_items,
+			METH_NOARGS,
+			"self, /",
+			"Return items (key, value) list (see dict.items)"),
+	PYRPN_method("step", rpnif_step,
+			METH_O,
+			"self, position, /",
+			"Run an IF given a position and return a new position"),
+	PYRPN_method("__getstate__", rpnif_getstate,
+			METH_NOARGS,
+			"self, /",
+			"Pickling method (see pickle module).\n"
+			"Return a bytes representation of the expression state."),
+	PYRPN_method("__setstate__", rpnif_setstate,
+			METH_O,
+			"self, state, /",
+			"Unpickling method (see pickle module)."),
 	{NULL} //Sentinel
 };
 
-PyMemberDef RPNIterExpr_members[] = {
+static PyMemberDef RPNIterExpr_members[] = {
 	{"expressions", T_OBJECT, offsetof(PyRPNIterExpr_t, expr), READONLY,
 		"The tuple of expressions"},
 	{NULL}
 };
 
-PySequenceMethods RPNIterExpr_seq_methods = {
+static PySequenceMethods RPNIterExpr_seq_methods = {
 	.sq_length = rpnif_len,
 	.sq_item = rpnif_expr_item,
 	.sq_ass_item = rpnif_expr_ass_item,
 };
 
-PyMappingMethods RPNIterExpr_mapping_methods = {
+static PyMappingMethods RPNIterExpr_mapping_methods = {
 	.mp_length = rpnif_len,
 	.mp_subscript = rpnif_subscript,
 	.mp_ass_subscript = rpnif_ass_subscript,
 };
 
-PyGetSetDef RPNIterExpr_getset[] = {
+static PyGetSetDef RPNIterExpr_getset[] = {
 	{NULL}
 };
 

python_if.h

@@ -50,12 +50,6 @@
  * This file is the header of the RPNIterExpr Python class
  */
 
-/**@brief RPNIterExpr Python class methods list
- * @ingroup python_if */
-extern PyMethodDef RPNIterExpr_methods[];
-/**@brief RPNIterExpr Python class members list
- * @ingroup python_if */
-extern PyMemberDef RPNIterExpr_members[];
 /**@brief RPNIterExpr Python class type definition
  * @ingroup python_if */
 extern PyTypeObject RPNIterExprType;

python_pyrpn.c

@@ -25,11 +25,15 @@
  * This file contains pyrpn Python module definition
  */
 
-PyMethodDef rpnmodule_methods[] = {
-	{"get_ops", (PyCFunction)pyrpn_ops, METH_NOARGS,
-		"Returns a valid operands dict"},
-	{"random_expr", (PyCFunction)pyrpn_random, METH_VARARGS | METH_KEYWORDS,
-		"Return a random RPN expression"},
+static PyMethodDef rpnmodule_methods[] = {
+	PYRPN_method("get_ops", pyrpn_ops,
+			METH_NOARGS,
+			"/",
+			"Return a dict with valid operands"),
+	PYRPN_method("random_expr", pyrpn_random,
+			METH_VARARGS | METH_KEYWORDS,
+			"args_count, token_count",
+			"Return a random RPN expression string"),
 	{NULL} // Sentinel
 };
 

python_pyrpn.h

@@ -66,9 +66,7 @@ extern PyTypeObject RPNExprType;
 /**@brief Python module initialization function
  * @ingroup python_module */
 PyMODINIT_FUNC PyInit_pyrpn(void);
-/**@brief pyrpn module methods list
- * @ingroup python_module */
-extern PyMethodDef rpnmodule_methods[];
+
 /**@brief Python module specs
  * @ingroup python_module */
 extern PyModuleDef rpnmodule;

python_rpnexpr.c

@@ -18,36 +18,52 @@
  */
 #include "python_rpnexpr.h"
 
-PyMethodDef RPNExpr_methods[] = {
-	{"random", (PyCFunction)rpnexpr_random, METH_CLASS | METH_VARARGS | METH_KEYWORDS,
-		"Return a new random RPN expression string"},
-	{"default_mutation_params", (PyCFunction)rpnexpr_default_mutation_params,
-		METH_CLASS | METH_FASTCALL,
-		"Return the default mutation parameters"},
-	{"eval", (PyCFunction)rpnexpr_eval, METH_FASTCALL, "Evaluate an expression"},
-	{"mutate", (PyCFunction)rpnexpr_mutate,
-		METH_VARARGS | METH_KEYWORDS,
-		"Mutate an expression given an RPNMutationParamsTuple instance"},
-	{"reset_stack", (PyCFunction)rpnexpr_reset_stack, METH_NOARGS,
-		"Reset stack memory storage (set all items to 0)"},
-	{"__getstate__", (PyCFunction)rpnexpr_getstate, METH_NOARGS,
-		"Pickling method. Return a bytes repr of tokenized expression \
-and the stack state."},
-	{"__setstate__", (PyCFunction)rpnexpr_setstate, METH_O,
-		"Unpickling method"},
-	{"__copy__", (PyCFunction)rpnexpr_copy, METH_NOARGS,
-		"Clone method. Return a new cloned instance"},
-	{"uid", (PyCFunction)rpnexpr_getexprstate, METH_NOARGS,
-		"Return a base64 uid for expression"},
+static PyMethodDef RPNExpr_methods[] = {
+	PYRPN_method("random", rpnexpr_random,
+			METH_CLASS | METH_VARARGS | METH_KEYWORDS,
+			"cls, args_count, token_count=10",
+			"Return a new random RPN expression string"),
+	PYRPN_method("default_mutation_params", rpnexpr_default_mutation_params,
+			METH_CLASS | METH_FASTCALL,
+			"cls, /",
+			"Return the default mutation parameters"),
+	PYRPN_method("eval", rpnexpr_eval, METH_FASTCALL,
+			"self, /, *args",
+			"Evaluate an expression"),
+	PYRPN_method("mutate", rpnexpr_mutate,
+			METH_VARARGS | METH_KEYWORDS,
+			"self, params=None, n_mutations=1",
+			"Mutate an expression"),
+	PYRPN_method("reset_stack", rpnexpr_reset_stack,
+			METH_NOARGS,
+			"self, /",
+			"Reset the stack (set all items to 0)"),
+	PYRPN_method("__getstate__", rpnexpr_getstate,
+			METH_NOARGS,
+			"self, /",
+			"Pickling method (see pickle module).\n"
+			"Return a bytes representation of the expression state."),
+	PYRPN_method("__setstate__", rpnexpr_setstate,
+			METH_O,
+			"self, state, /",
+			"Unpickling method (see pickle module)."),
+	PYRPN_method("__copy__", rpnexpr_copy,
+			METH_NOARGS,
+			"self, /",
+			"Return a new equivalent instance (see copy module)"),
+	PYRPN_method("uid", rpnexpr_getexprstate,
+			METH_NOARGS,
+			"self, /",
+			"Return a base64 uid for expression"),
 	{NULL} //Sentinel
 };
 
-PyMemberDef RPNExpr_members[] = {
+static PyMemberDef RPNExpr_members[] = {
 	{NULL}
 };
 
 /**@todo Continue sequence implementation with contains, concat, repeat etc. */
-PySequenceMethods RPNExpr_seq_methods = {
+static PySequenceMethods RPNExpr_seq_methods = {
 	.sq_length = rpnexpr_len,
 	.sq_item = rpnexpr_token_item,
 	.sq_ass_item = rpnexpr_token_ass_item,

python_rpnexpr.h

@@ -45,12 +45,6 @@
  *
  */
 
-/**@brief RPNExpr Python class methods list
- * @ingroup python_type */
-extern PyMethodDef RPNExpr_methods[];
-/**@brief RPNExpr Python class members list
- * @ingroup python_type */
-extern PyMemberDef RPNExpr_members[];
 /**@brief RPNExpr Python class type definition
  * @ingroup python_type */
 extern PyTypeObject RPNExprType;

python_rpntoken.c

@@ -1,8 +1,9 @@
 #include "python_rpntoken.h"
 
 static PyMethodDef RPNToken_methods[] = {
-	{"from_str", (PyCFunction)rpntoken_from_str, METH_CLASS | METH_O,
-		"Return a new RPNToken subclass instance from string"},
+	PYRPN_method("from_str", rpntoken_from_str, METH_CLASS | METH_O,
+			"cls, token_str, /",
+			"Return a new RPNToken subclass instance from string"),
 	{NULL} //
 };
 
@@ -22,13 +23,16 @@ PyTypeObject RPNTokenType = {
 };
 
 static PyMethodDef RPNTokenOp_methods[] = {
-	{"opcode_max", (PyCFunction)rpntokenop_opcode_max,
-		 METH_STATIC | METH_NOARGS,
-		"Return the maximum valid value for an opcode"},
-	{"chr", (PyCFunction)rpntokenop_opchr, METH_NOARGS,
-		"Return the single char representation of the operand"},
-	{"str", (PyCFunction)rpntokenop_opstr, METH_NOARGS,
-		"Return the string (multi-char) representation of the operand"},
+	PYRPN_method("opcode_max", rpntokenop_opcode_max,
+			METH_STATIC | METH_NOARGS,
+			"",
+			"Return the maximum valid value for an opcode"),
+	PYRPN_method("chr", rpntokenop_opchr, METH_NOARGS,
+			"self, /",
+			"Return the single char representation of operand"),
+	PYRPN_method("str", rpntokenop_opstr, METH_NOARGS,
+			"self, /",
+			"Return the string (multi-char) representation of the operand"),
 	{NULL} //
 };