Updated contribution and statedata callback docs

CONTRIBUTING.md

@@ -68,7 +68,7 @@ In some cases, Clixon uses three-value returns as follows:
 ### Return values
 
 Clixon uses goto:s only to get a single point of exit functions as follows::
-
+```
   {
       int retval = -1;
   
@@ -77,6 +77,7 @@ Clixon uses goto:s only to get a single point of exit functions as follows::
     done:
       return retval
   }
+```
 
 Notes:
 
@@ -98,24 +99,28 @@ How to document the code:
    * This is a detailed description
    * spanning several lines.
    *
+   * @param[in]     src     This is a description of the first parameter
+   * @param[in,out] dest    This is a description of the second parameter
+   * @retval        0       This is a description of the return value
+   * @retval       -1       This is a description of another return value
+   *
    * Example usage:
    * @code
    *   fn(a, &b);
    * @endcode
    *
-   * @param[in]     src     This is a description of the first parameter
-   * @param[in,out] dest    This is a description of the second parameter
-   * @retval        0       This is a description of the return value
-   * @retval       -1       This is a description of another return value
    * @see                   See also this function
    */
 ```
 
 ## Testing
 
-For a new feature, you need to write [a CI test](https://github.com/clicon/clixon/blob/master/test/README.md), including some functionality tests and preferably some negative tests. Tests are then run automatically as regression on commit [by github actions](https://github.com/clicon/clixon/actions/).
+For a new feature, it is important to write (or extend) [a clixon test](https://github.com/clicon/clixon/blob/master/test/README.md), including some functionality tests and preferably some negative tests. Tests are then run automatically as regression on commit [by github actions](https://github.com/clicon/clixon/actions/).
 
 These tests are also the basis for more extensive CI tests run by the project which
-include [memory tests](https://github.com/clicon/clixon/tree/master/test#memory-leak-test), [vagrant tests on other platforms](https://github.com/clicon/clixon/tree/master/test/vagrantvalgrind), [coverage tests](https://app.codecov.io/gh/clicon/clixon) and occasional [fuzzing with AFL](https://github.com/clicon/clixon/tree/master/fuzz).
+include:
-
+- [memory tests](https://github.com/clicon/clixon/tree/master/test#memory-leak-test). Running the .mem.sh for cli, backend,netconf and restconf is mandatory.
-In particular, a new feature must pass the [memory tests](https://github.com/clicon/clixon/tree/master/test#memory-leak-test).
+- [Vagrant tests on other operating systems](https://github.com/clicon/clixon/tree/master/test/vagrant]. Other OS:s include ubuntu, centos and freebsd
+- [CI on other platforms](https://github.com/clicon/clixon/tree/master/test/cicd]. Other platforms include x86-64, 32-bit i686, and armv71
+- [coverage tests](https://app.codecov.io/gh/clicon/clixon)
+- [fuzzing with AFL](https://github.com/clicon/clixon/tree/master/test/fuzz) (occasionally)

apps/backend/backend_plugin.c

@@ -453,11 +453,11 @@ clixon_plugin_lockdb_all(clicon_handle h,
  */
 int
 clixon_pagination_cb_call(clicon_handle h,
-			   char        *xpath,
+			  char        *xpath,
-			   int          locked,
+			  int          locked,
-			   uint32_t     offset,
+			  uint32_t     offset,
-			   uint32_t     limit,
+			  uint32_t     limit,
-			   cxobj       *xstate)
+			  cxobj       *xstate)
 {
     int                 retval = -1;
     pagination_data_t   pd;

lib/clixon/clixon_plugin.h

@@ -196,13 +196,24 @@ typedef int (plgauth_t)(clicon_handle h, void *req, clixon_auth_type_t auth_type
 */
 typedef int (plgreset_t)(clicon_handle h, const char *db); 
 
-/* Plugin statedata
+/* Provide state data from plugin
+ *
+ * A complete valid XML tree is created by the plugin and sent back via xtop, which is merged
+ * into a complete state tree by the system.
+ * The plugin should ensure that xpath is matched (using namspace context nsc)
+ * This callback may be replaced with a "dispatcher" type API in the future where the
+ * XPath binding is stricter, similar to the pagination API.
+ *
  * @param[in]  h          Clicon handle
  * @param[in]  xpath      Part of state requested
  * @param[in]  nsc        XPATH namespace context.
  * @param[out] xtop       XML tree where statedata is added
  * @retval    -1          Fatal error
  * @retval     0          OK
+ *
+ * @note The system will make an xpath check and filter out non-matching trees
+ * @note The system does not validate the xml, unless CLICON_VALIDATE_STATE_XML is set
+ * @see clixon_pagination_cb_register for special paginated state data callback
  */
 typedef int (plgstatedata_t)(clicon_handle h, cvec *nsc, char *xpath, cxobj *xtop);
 
@@ -293,7 +304,7 @@ struct clixon_plugin_api{
             plgdaemon_t      *cb_daemon;         /* Plugin daemonized (always called) */
 	    plgreset_t       *cb_reset;          /* Reset system status */
 
-	    plgstatedata_t   *cb_statedata;      /* Get state data from plugin (backend only) */
+	    plgstatedata_t   *cb_statedata;      /* Provide state data XML from plugin */
 	    plglockdb_t      *cb_lockdb;         /* Database lock changed state */
 	    trans_cb_t       *cb_trans_begin;	 /* Transaction start */
 	    trans_cb_t       *cb_trans_validate; /* Transaction validation */