defining data structures for validation

[oweals/gnunet.git] / src / include / gnunet_testing_lib.h

diff --git a/src/include/gnunet_testing_lib.h b/src/include/gnunet_testing_lib.h
index 04975d07740785dd1f3ddd57a8f2c90ecf286caf..0317b20073add209c192cd23c5032bfeaf731965 100644 (file)
--- a/src/include/gnunet_testing_lib.h
+++ b/src/include/gnunet_testing_lib.h
@@ -1,33 +1,41 @@
 /*
       This file is part of GNUnet
-      Copyright (C) 2008, 2009, 2012 Christian Grothoff (and other contributing authors)
+      Copyright (C) 2008, 2009, 2012 GNUnet e.V.
 
-      GNUnet is free software; you can redistribute it and/or modify
-      it under the terms of the GNU General Public License as published
-      by the Free Software Foundation; either version 3, or (at your
-      option) any later version.
+      GNUnet is free software: you can redistribute it and/or modify it
+      under the terms of the GNU Affero General Public License as published
+      by the Free Software Foundation, either version 3 of the License,
+      or (at your option) any later version.
 
       GNUnet is distributed in the hope that it will be useful, but
       WITHOUT ANY WARRANTY; without even the implied warranty of
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-      General Public License for more details.
+      Affero General Public License for more details.
+     
+      You should have received a copy of the GNU Affero General Public License
+      along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
-      You should have received a copy of the GNU General Public License
-      along with GNUnet; see the file COPYING.  If not, write to the
-      Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-      Boston, MA 02111-1307, USA.
+     SPDX-License-Identifier: AGPL3.0-or-later
  */
 
 /**
- * @file include/gnunet_testing_lib.h
- * @brief convenience API for writing testcases for GNUnet;
- *        can start/stop one or more peers on a system;
- *        testing is responsible for managing private keys,
- *        ports and paths; it is a low-level library that
- *        does not support higher-level functions such as
- *        P2P connection, topology management or distributed
- *        testbed maintenance (those are in gnunet_testbed_service.h)
  * @author Christian Grothoff
+ *
+ * @file
+ * Convenience API for writing testcases for GNUnet
+ *
+ * @defgroup testing  Testing library
+ * Library for writing testcases for GNUnet.
+ *
+ * It can start/stop one or more peers on a system; testing is responsible for
+ * managing private keys, ports and paths; it is a low-level library that does
+ * not support higher-level functions such as P2P connection, topology
+ * management or distributed testbed maintenance (those are provided by the
+ * [Testbed service](@ref testbed))
+ *
+ * @see [Documentation](https://gnunet.org/writing_testcases)
+ *
+ * @{
  */
 
 #ifndef GNUNET_TESTING_LIB_H
@@ -149,9 +157,7 @@ struct GNUNET_TESTING_System *
 GNUNET_TESTING_system_create_with_portrange (const char *testdir,
                                             const char *trusted_ip,
                                             const char *hostname,
-                                             const struct
-                                             GNUNET_TESTING_SharedService *
-                                             shared_services,
+                                             const struct GNUNET_TESTING_SharedService *shared_services,
                                             uint16_t lowport,
                                             uint16_t highport);
 
@@ -177,12 +183,12 @@ GNUNET_TESTING_system_destroy (struct GNUNET_TESTING_System *system,
  * GNUnet source code.
  *
  * This is primarily a helper function used internally
- * by 'GNUNET_TESTING_peer_configure'.
+ * by #GNUNET_TESTING_peer_configure().
  *
  * @param system the testing system handle
  * @param key_number desired pre-created hostkey to obtain
  * @param id set to the peer's identity (hash of the public
- *        key; if NULL, GNUNET_SYSERR is returned immediately
+ *        key; if NULL, #GNUNET_SYSERR is returned immediately
  * @return NULL on error (not enough keys)
  */
 struct GNUNET_CRYPTO_EddsaPrivateKey *
@@ -219,10 +225,10 @@ GNUNET_TESTING_release_port (struct GNUNET_TESTING_System *system,
  * system. The default configuration will be available in PATHS section under
  * the option DEFAULTCONFIG after the call. SERVICE_HOME is also set in PATHS
  * section to the temporary directory specific to this configuration. If we run
- * out of "*port" numbers, return SYSERR.
+ * out of "*port" numbers, return #GNUNET_SYSERR.
  *
  * This is primarily a helper function used internally
- * by 'GNUNET_TESTING_peer_configure'.
+ * by #GNUNET_TESTING_peer_configure().
  *
  * @param system system to use to coordinate resource usage
  * @param cfg template configuration to update
@@ -345,9 +351,9 @@ typedef void
  *
  * @param peer the peer to stop
  * @param cb the callback to signal peer shutdown
- * @param cb_cls closure for the above callback
- * @return GNUNET_OK upon successfully giving the request to the ARM API (this
- *           does not mean that the peer is successfully stopped); GNUNET_SYSERR
+ * @param cb_cls closure for the @a cb
+ * @return #GNUNET_OK upon successfully giving the request to the ARM API (this
+ *           does not mean that the peer is successfully stopped); #GNUNET_SYSERR
  *           upon any error.
  */
 int
@@ -460,3 +466,5 @@ GNUNET_TESTING_get_testname_from_underscore (const char *argv0);
 #endif
 
 #endif
+
+/** @} */  /* end of group */