TESTING: Various notes on API

3 files changed, 46 insertions, 16 deletions

diff --git a/src/include/gnunet_testing_barrier.h b/src/include/gnunet_testing_barrier.h
index ed4624e1b..b02499d14 100644
--- a/src/include/gnunet_testing_barrier.h
+++ b/src/include/gnunet_testing_barrier.h
@@ -67,6 +67,7 @@ struct GNUNET_TESTING_BarrierList
 
 /**
  * Message send to a child loop to inform the child loop about a barrier being advanced.
+ * FIXME: This is not packed and contains a char*... no payload documentation.
  */
 struct GNUNET_TESTING_CommandBarrierAdvanced
 {
@@ -84,6 +85,7 @@ struct GNUNET_TESTING_CommandBarrierAdvanced
 /**
  * Message send by a child loop to inform the master loop how much
  * GNUNET_CMDS_BARRIER_REACHED messages the child will send.
+ * FIXME: Not packed and contains char*; int in NBO? bitlength undefined.
  */
 struct GNUNET_TESTING_CommandBarrierAttached
 {
@@ -109,6 +111,7 @@ struct GNUNET_TESTING_CommandBarrierAttached
 };
 
 
+// FIXME: See above
 struct GNUNET_TESTING_CommandBarrierReached
 {
   /**
@@ -138,6 +141,12 @@ struct GNUNET_TESTING_CommandBarrierReached
 struct GNUNET_TESTING_Barrier*
 GNUNET_TESTING_barrier_new (const char *testcase_name);
 
+/**
+ * FIXME: documentation
+ * FIXME: high-level it is baffling how we need both the GNUNET_TESTING_Barrier
+ * and the Command that creates barriers. Conceptually this seems to be
+ * very much separate. Can we move _Barrier completely into testing as private?
+ */
 struct GNUNET_TESTING_Command
 GNUNET_TESTING_cmd_barrier_create (
  const char *label,
@@ -149,6 +158,7 @@ GNUNET_TESTING_cmd_barrier_create (
 // async version implies reached but does not
 // wait on other peers to reach it.
 /**
+ * FIXME: Documentation
  * Create command.
  *
  * @param label name for command.
@@ -171,6 +181,8 @@ GNUNET_TESTING_cmd_barrier_reached (
 
 
 /**
+ * FIXME: Return type
+ * FIXME: Documentation
  * Can we advance the barrier?
  *
  * @param barrier The barrier in question.
@@ -181,6 +193,7 @@ GNUNET_TESTING_can_barrier_advance (struct GNUNET_TESTING_Barrier *barrier);
 
 
 /**
+ * FIXME: Naming
  * Send Message to netjail nodes that a barrier can be advanced.
  *
  * @param is The interpreter loop.
diff --git a/src/include/gnunet_testing_netjail_lib.h b/src/include/gnunet_testing_netjail_lib.h
index 53cae38c6..eb16f6b86 100644
--- a/src/include/gnunet_testing_netjail_lib.h
+++ b/src/include/gnunet_testing_netjail_lib.h
@@ -50,6 +50,7 @@ struct GNUNET_TESTING_NetjailRouter
 
 
 /**
+ * FIXME: Naming
  * Enum for the different types of nodes.
  */
 enum GNUNET_TESTING_NODE_TYPE
@@ -265,6 +266,7 @@ GNUNET_TESTING_get_topo_from_file (const char *filename);
 
 
 /**
+ * FIXME: this could use a "to_string".
  * Parse the topology data.
  *
  * @param data The topology data.
@@ -386,6 +388,7 @@ struct GNUNET_TESTING_TestState
 };
 
 /**
+ * FIXME: This was also not namespaces.
  * Struct with information for callbacks.
  *
  */
@@ -408,6 +411,7 @@ struct GNUNET_TESTING_BlockState
 };
 
 /**
+ * FIXME: This was also not namespaced
  * Struct to hold information for callbacks.
  *
  */
@@ -426,7 +430,7 @@ struct GNUNET_TESTING_LocalPreparedState
 };
 
 /**
- * Create command.
+ * Create command. FIXME: What?
  *
  * @param label name for command.
  * @param create_label Label of the cmd which started the test system.
@@ -437,13 +441,14 @@ struct GNUNET_TESTING_Command
 GNUNET_TESTING_cmd_system_destroy (const char *label,
                                    const char *create_label);
 
-
+//FIXME
 struct GNUNET_TESTING_Command
 GNUNET_TESTING_cmd_system_create (const char *label,
                                   const char *testdir);
 
 
 /**
+ * FIXME
  * Create command.
  *
  * @param label name for command.
@@ -458,6 +463,7 @@ GNUNET_TESTING_cmd_netjail_start (const char *label,
 
 
 /**
+ * FIXME
  * Create command.
  *
  * @param label name for command.
@@ -472,6 +478,8 @@ GNUNET_TESTING_cmd_netjail_stop (const char *label,
 
 
 /**
+ * FIXME
+ * FIXME Naming?
  * Create command.
  *
  * @param label Name for the command.
@@ -506,6 +514,8 @@ GNUNET_TESTING_cmd_stop_testing_system (
 
 /**
  * Create a GNUNET_CMDS_LOCAL_FINISHED message.
+ * FIXME: This is strange as messages are not really used
+ * like this. Consider removing.
  *
  * @return The GNUNET_CMDS_LOCAL_FINISHED message.
  */
@@ -513,6 +523,7 @@ struct GNUNET_MessageHeader *
 GNUNET_TESTING_send_local_test_finished_msg ();
 
 
+//FIXME
 struct GNUNET_TESTING_Command
 GNUNET_TESTING_cmd_block_until_all_peers_started (
   const char *label,
@@ -520,6 +531,7 @@ GNUNET_TESTING_cmd_block_until_all_peers_started (
 
 
 /**
+ * FIXME
  * Create command.
  *
  * @param label name for command.
@@ -532,6 +544,7 @@ GNUNET_TESTING_cmd_block_until_external_trigger (
   const char *label);
 
 /**
+ * FIXME
  * Create command.
  *
  * @param label name for command.
@@ -544,6 +557,7 @@ GNUNET_TESTING_cmd_send_peer_ready (const char *label,
 
 
 /**
+ * FIXME
  * Create command.
  *
  * @param label name for command.
@@ -556,6 +570,7 @@ GNUNET_TESTING_cmd_local_test_finished (
   GNUNET_TESTING_cmd_helper_write_cb write_message);
 
 /**
+ * FIXME
  * Create command.
  *
  * @param label name for command.
diff --git a/src/include/gnunet_testing_ng_lib.h b/src/include/gnunet_testing_ng_lib.h
index d218a65db..270fdab26 100644
--- a/src/include/gnunet_testing_ng_lib.h
+++ b/src/include/gnunet_testing_ng_lib.h
@@ -328,6 +328,9 @@ GNUNET_TESTING_cmd_end (void);
 
 /**
  * Turn asynchronous command into non blocking command by setting asynchronous_finish to true.
+ * FIXME: what is this API doing? Is it returning a new cmd which is unblocking?
+ * Is it modifying cmd?
+ * Looking at the code, it both modifying cmd AND returning a copy oO
  *
  * @param cmd command to make synchronous.
  * @return a finish-command.
@@ -370,6 +373,8 @@ GNUNET_TESTING_cmd_rewind_ip (const char *label,
 
 /**
  * Function called with the final result of the test.
+ * FIXME: This may want to use a GNUNET_ErrorCode (namespaced, e.g.
+ * GNUNET_EC_TESTING_*)
  *
  * @param cls closure
  * @param rv #GNUNET_OK if the test passed
@@ -385,7 +390,7 @@ typedef void
  * defined into the "run" method that returns after
  * having scheduled the test interpreter.
  *
- * @param commands the list of command to execute
+ * @param commands the array of command to execute
  * @param timeout how long to wait for each command to execute
  * @param rc function to call with the final result
  * @param rc_cls closure for @a rc
@@ -402,6 +407,7 @@ GNUNET_TESTING_run (const struct GNUNET_TESTING_Command *commands,
  * Start a GNUnet scheduler event loop and
  * run the testsuite.  Return 0 upon success.
  * Expected to be called directly from main().
+ * FIXME: Why is this commands array here not const?
  *
  * @param commands the list of command to execute
  * @param timeout how long to wait for each command to execute
@@ -413,19 +419,6 @@ GNUNET_TESTING_main (struct GNUNET_TESTING_Command *commands,
 
 
 /**
- * Look for substring in a programs' name.
- *
- * @param prog program's name to look into
- * @param marker chunk to find in @a prog
- * // FIXME: this does not belong here! => libgnunetutil, maybe?
- * // FIXME: return bool? document return value!
- * // FIXME: man strstr??
- */
-int
-GNUNET_TESTING_has_in_name (const char *prog,
-                            const char *marker);
-
-/**
   * Deleting all barriers create in the context of this interpreter.
   *
   * @param is The interpreter.
@@ -473,6 +466,8 @@ GNUNET_TESTING_add_netjail_helper (struct GNUNET_TESTING_Interpreter *is,
 
 /**
  * Send Message to netjail nodes that a barrier can be advanced.
+ * FIXME: Naming. No "netjail" in argument. Or is there a
+ * GNUNET_TESTING_send_message without "to_netjail"??
  *
  * @param is The interpreter.
  * @param global_node_number The node to inform.
@@ -486,6 +481,8 @@ GNUNET_TESTING_send_message_to_netjail (struct GNUNET_TESTING_Interpreter *is,
 
 /**
  * Returns the actual running command.
+ * FIXME: Is Command allocated? Is it constant? Should this be a private
+ * function? => not used outside of testing
  *
  * @param is Global state of the interpreter, used by a command
  *        to access information about other commands.
@@ -498,6 +495,7 @@ GNUNET_TESTING_interpreter_get_current_command (
 
 /**
  * Check if the command is running.
+ * FIXME: Unused function.
  *
  * @param command The command to check.
  * @return GNUNET_NO if the command is not running, GNUNET_YES if it is running.
@@ -508,6 +506,7 @@ GNUNET_TESTING_running (const struct GNUNET_TESTING_Command *command);
 
 /**
  * Check if a command is finished.
+ * FIXME: Unused function
  *
  * @param command The command to check.
  * @return GNUNET_NO if the command is not finished, GNUNET_YES if it is finished.
@@ -595,6 +594,7 @@ struct GNUNET_TESTING_Timer
 
 /**
  * Retrieve the public key from the test system with the unique node id.
+ * FIXME: Naming. => get_peer? This returns a PeerIdentity not a PublicKey
  *
  * @param num The unique node id.
  * @param tl_system The test system.
@@ -618,6 +618,7 @@ GNUNET_TESTING_cmd_stat (struct GNUNET_TESTING_Timer *timers);
 /* *** Generic trait logic for implementing traits ********* */
 
 /**
+ * FIXME: Documentation
  * A trait.
  */
 struct GNUNET_TESTING_Trait
@@ -652,6 +653,7 @@ GNUNET_TESTING_trait_end (void);
 
 /**
  * Extract a trait.
+ * FIXME: Naming. This is something like "contains trait".
  *
  * @param traits the array of all the traits.
  * @param[out] ret where to store the result.