Please note that active projects have migrated to https://github.com/fawkesrobotics.

eclipse-clp: fix docstring errors
authorVictor Mataré <matare@lih.rwth-aachen.de>
Tue, 29 May 2018 20:09:24 +0000 (22:09 +0200)
committerVictor Mataré <matare@lih.rwth-aachen.de>
Tue, 29 May 2018 20:58:05 +0000 (22:58 +0200)
Also rename the eclipse terms created by the blackboard event handlers,
but those aren't used anywhere, anyways. Blackboard event handler stuff
is also mostly untested.

src/plugins/eclipse-clp/blackboard_listener_thread.cpp
src/plugins/eclipse-clp/blackboard_listener_thread.h
src/plugins/eclipse-clp/externals/blackboard.cpp
src/plugins/eclipse-clp/externals/blackboard.h

index 9e8cf0e..53c313c 100644 (file)
@@ -1,8 +1,28 @@
+/***************************************************************************
+ *  blackboard_listener_thread.cpp - Convert blackboard events to eclipse terms
+ *
+ *  Copyright  2017  Victor Mataré
+ ****************************************************************************/
+
+/*  This program 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 2 of the License, or
+ *  (at your option) any later version.
+ *
+ *  This program 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 Library General Public License for more details.
+ *
+ *  Read the full text in the LICENSE.GPL file in the doc directory.
+ */
+
 #include "blackboard_listener_thread.h"
 
 #include <core/threading/mutex_locker.h>
 
 using namespace fawkes;
+using namespace std;
 
 BlackboardListenerThread *BlackboardListenerThread::instance_ = nullptr;
 
@@ -13,6 +33,9 @@ BlackboardListenerThread::BlackboardListenerThread()
 }
 
 
+/** Get the singleton instance of this thread
+ * @return THE instance
+ */
 BlackboardListenerThread *BlackboardListenerThread::instance()
 {
   if (!instance_)
@@ -21,10 +44,15 @@ BlackboardListenerThread *BlackboardListenerThread::instance()
 }
 
 
+/** Delete singleton instance, e.g. when unloading the plugin */
 void BlackboardListenerThread::cleanup_instance()
 { delete instance_; }
 
 
+/** Trigger events if an interface matching the pattern is created or destroyed
+ * @param type_pattern See BlackBoardInterfaceObserver::bbio_add_observed_create
+ * @param id_pattern See BlackBoardInterfaceObserver::bbio_add_observed_create
+ */
 void BlackboardListenerThread::observe_pattern(
     const char *type_pattern, const char *id_pattern) noexcept
 {
@@ -34,6 +62,7 @@ void BlackboardListenerThread::observe_pattern(
 }
 
 
+/** Register @param interface for change notifications */
 void BlackboardListenerThread::listen_for_change(Interface *interface) noexcept
 {
   MutexLocker lock(&state_mutex_);
@@ -41,6 +70,10 @@ void BlackboardListenerThread::listen_for_change(Interface *interface) noexcept
 }
 
 
+/** Called by the BlackBoardInterfaceObserver when an interface matching a subscribed pattern is created
+ * @param type Interface type name
+ * @param id Interface ID
+ */
 void BlackboardListenerThread::bb_interface_created(const char *type, const char *id) noexcept
 {
   MutexLocker lock(&state_mutex_);
@@ -48,6 +81,10 @@ void BlackboardListenerThread::bb_interface_created(const char *type, const char
 }
 
 
+/** Called by the BlackBoardInterfaceObserver when an interface is destroyed
+ * @param type Interface type name
+ * @param id Interface ID
+ */
 void BlackboardListenerThread::bb_interface_destroyed(const char *type, const char *id) noexcept
 {
   MutexLocker lock(&state_mutex_);
@@ -55,6 +92,9 @@ void BlackboardListenerThread::bb_interface_destroyed(const char *type, const ch
 }
 
 
+/** Called by the BlackBoardInterfaceListener when an interface changes
+ * @param interface The changed interface
+ */
 void BlackboardListenerThread::bb_interface_data_changed(Interface *interface) noexcept
 {
   MutexLocker lock(&state_mutex_);
@@ -62,6 +102,9 @@ void BlackboardListenerThread::bb_interface_data_changed(Interface *interface) n
 }
 
 
+/** Test whether any events are in the queue
+ * @return Whether any events are in the queue
+ */
 bool BlackboardListenerThread::event_pending()
 {
   MutexLocker lock(&state_mutex_);
@@ -69,6 +112,9 @@ bool BlackboardListenerThread::event_pending()
 }
 
 
+/** Return and remove the next event in the queue
+ * @return The next event
+ */
 shared_ptr<BlackboardListenerThread::Event> BlackboardListenerThread::event_pop()
 {
   MutexLocker lock(&state_mutex_);
@@ -78,15 +124,24 @@ shared_ptr<BlackboardListenerThread::Event> BlackboardListenerThread::event_pop(
 }
 
 
+/** Return an eclipse term representing the event
+ * @return An eclipse term representing the event: bb_created(UID)
+ */
 BlackboardListenerThread::Created::operator EC_word ()
-{ return ::term(EC_functor("bb_create", 1), uid().c_str()); }
+{ return ::term(EC_functor("bb_created", 1), uid().c_str()); }
 
 
+/** Return an eclipse term representing the event
+ * @return An eclipse term representing the event: bb_destroyed(UID)
+ */
 BlackboardListenerThread::Destroyed::operator EC_word ()
-{ return ::term(EC_functor("bb_destroy", 1), uid().c_str()); }
+{ return ::term(EC_functor("bb_destroyed", 1), uid().c_str()); }
 
 
+/** Return an eclipse term representing the event
+ * @return An eclipse term representing the event: bb_changed(UID)
+ */
 BlackboardListenerThread::Changed::operator EC_word ()
-{ return ::term(EC_functor("bb_change", 1), uid().c_str()); }
+{ return ::term(EC_functor("bb_changed", 1), uid().c_str()); }
 
 
index 5c780c8..d1507d3 100644 (file)
@@ -1,3 +1,22 @@
+/***************************************************************************
+ *  blackboard_listener_thread.h - Convert blackboard events to eclipse terms
+ *
+ *  Copyright  2017  Victor Mataré
+ ****************************************************************************/
+
+/*  This program 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 2 of the License, or
+ *  (at your option) any later version.
+ *
+ *  This program 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 Library General Public License for more details.
+ *
+ *  Read the full text in the LICENSE.GPL file in the doc directory.
+ */
+
 #ifndef BLACKBOARD_LISTENER_THREAD_H
 #define BLACKBOARD_LISTENER_THREAD_H
 
 #include "externals/blackboard.h"
 
 
-using namespace std;
-using namespace fawkes;
-
-
+/** Keeps a queue of subscribed blackboard events that can be queried in a thread-safe manner */
 class BlackboardListenerThread
     : public fawkes::Thread
     , public fawkes::LoggingAspect
@@ -32,6 +48,14 @@ class BlackboardListenerThread
     , public fawkes::BlackBoardInterfaceObserver
     , public fawkes::BlackBoardInterfaceListener
 {
+private:
+  using string = std::string;
+  template<class T> using queue = std::queue<T>;
+  template<class T> using shared_ptr = std::shared_ptr<T>;
+  template<class T1, class T2> using map = std::map<T1, T2>;
+  using Interface = fawkes::Interface;
+  using Mutex = fawkes::Mutex;
+
 public:
   BlackboardListenerThread();
 
@@ -46,24 +70,40 @@ public:
   static void cleanup_instance();
 
 
+  /** Abstract superclass for blackboard events */
   class Event {
   public:
+    /** Constructor
+     * @param type Blackboard interface type as string
+     * @param id Blackboard interface ID
+     */
     Event(const std::string &type, const std::string &id)
       : type(type), id(id)
     {}
 
     virtual ~Event();
 
+    /** Return an eclipse term representing the event (abstract)
+     * @return An eclipse term representing the event (abstract)
+     */
     virtual operator EC_word () = 0;
 
+    /** Return the UID (i.e. type::id) of the blackboard interface that triggered the event
+     * @return The UID (i.e. type::id) of the blackboard interface that triggered the event
+     */
     std::string uid()
     { return type + "::" + id; }
 
   protected:
-    std::string type, id;
+    /** Triggering interface's type name */
+    string type;
+
+    /** Triggering interface's ID */
+    string id;
   };
 
 
+  /** A new interface was created */
   class Created : public Event {
   public:
     using Event::Event;
@@ -71,6 +111,7 @@ public:
   };
 
 
+  /** An interface was destroyed */
   class Destroyed : public Event {
   public:
     using Event::Event;
@@ -78,11 +119,16 @@ public:
   };
 
 
+  /** An interface changed */
   class Changed : public Event {
   public:
+    /** Constructor
+     * @param interface The interface that changed
+     */
     Changed(Interface *interface)
       : Event(interface->type(), interface->id()), interface(interface)
     {}
+
     virtual operator EC_word ();
 
   private:
@@ -90,7 +136,6 @@ public:
   };
 
 
-
   bool event_pending();
   shared_ptr<Event> event_pop();
 
index 7759687..bace997 100644 (file)
@@ -59,6 +59,7 @@ EclExternalBlackBoard*  EclExternalBlackBoard::m_instance = NULL;
 
   /** Creates the initial EclExternalBlackBoard object
    * @param bb pointer to the BlackBoard to be used
+   * @param logger pointer to the Logger to be used
    */
   void EclExternalBlackBoard::create_initial_object(BlackBoard *bb, Logger *logger)
   {
index 4a57258..d304ad1 100644 (file)
@@ -55,7 +55,14 @@ public:
   static BlackBoard* blackboard_instance();
   std::map<std::string, Interface *> & interfaces();
 
+  /**
+   * @return A pointer to the plugin-central logger
+   */
   static Logger *logger() { return m_logger; }
+
+  /**
+   * @return Name for logging
+   */
   static const char *name() { return "EclExternalBlackBoard"; }
 
 private: