From: Martin Quinson <martin.quinson@loria.fr>
Date: Fri, 10 Aug 2018 13:43:04 +0000 (+0200)
Subject: improve doxygen comments in s4u
X-Git-Tag: v3_21~262
X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/6bc18b576fa4a890d8b9916d292ca67dfbf60dd3

improve doxygen comments in s4u
---

diff --git a/include/simgrid/s4u/Activity.hpp b/include/simgrid/s4u/Activity.hpp
index 615f7bb3ba..6cd6276393 100644
--- a/include/simgrid/s4u/Activity.hpp
+++ b/include/simgrid/s4u/Activity.hpp
@@ -27,6 +27,7 @@ namespace s4u {
  * - Synchronization activities may possibly be connected to no action.
  */
 class XBT_PUBLIC Activity {
+#ifndef DOXYGEN
   friend Comm;
   friend XBT_PUBLIC void intrusive_ptr_release(Comm * c);
   friend XBT_PUBLIC void intrusive_ptr_add_ref(Comm * c);
@@ -36,6 +37,7 @@ class XBT_PUBLIC Activity {
   friend Io;
   friend XBT_PUBLIC void intrusive_ptr_release(Io* i);
   friend XBT_PUBLIC void intrusive_ptr_add_ref(Io* i);
+#endif
 
 protected:
   Activity()  = default;
diff --git a/include/simgrid/s4u/Actor.hpp b/include/simgrid/s4u/Actor.hpp
index 09e3df6803..cf5f0f10ef 100644
--- a/include/simgrid/s4u/Actor.hpp
+++ b/include/simgrid/s4u/Actor.hpp
@@ -18,7 +18,7 @@
 namespace simgrid {
 namespace s4u {
 
-/** @ingroup s4u_api
+/**
  *
  * An actor is an independent stream of execution in your distributed application.
  *
@@ -121,10 +121,12 @@ namespace s4u {
 
 /** @brief Simulation Agent */
 class XBT_PUBLIC Actor : public simgrid::xbt::Extendable<Actor> {
+#ifndef DOXYGEN
   friend Exec;
   friend Mailbox;
   friend simgrid::kernel::actor::ActorImpl;
   friend simgrid::kernel::activity::MailboxImpl;
+#endif
   kernel::actor::ActorImpl* pimpl_ = nullptr;
 
   /** Wrap a (possibly non-copyable) single-use task into a `std::function` */
@@ -169,12 +171,16 @@ public:
   /** Signal indicating that the given actor is about to disappear */
   static simgrid::xbt::signal<void(simgrid::s4u::ActorPtr)> on_destruction;
 
-  /** Create an actor using a function
+  /** Create an actor from a std::function
    *
    *  If the actor is restarted, the actor has a fresh copy of the function.
    */
   static ActorPtr create(std::string name, s4u::Host* host, std::function<void()> code);
 
+  /** Create an actor from a std::function
+   *
+   *  If the actor is restarted, the actor has a fresh copy of the function.
+   */
   static ActorPtr create(std::string name, s4u::Host* host, std::function<void(std::vector<std::string>*)> code,
                          std::vector<std::string>* args)
   {
@@ -245,6 +251,15 @@ public:
   /** Retrieves the time at which that actor will be killed (or -1 if not set) */
   double get_kill_time();
 
+  /** @brief Moves the actor to another host
+   *
+   * If the actor is currently blocked on an execution activity, the activity is also
+   * migrated to the new host. If it's blocked on another kind of activity, an error is
+   * raised as the mandated code is not written yet. Please report that bug if you need it.
+   *
+   * Asynchronous activities started by the actor are not migrated automatically, so you have
+   * to take care of this yourself (only you knows which ones should be migrated).
+   */
   void migrate(Host * new_host);
 
   /** Ask the actor to die.
@@ -262,7 +277,7 @@ public:
   /** Retrieves the actor that have the given PID (or nullptr if not existing) */
   static ActorPtr by_pid(aid_t pid);
 
-  /** @brief Wait for the actor to finish.
+  /** Wait for the actor to finish.
    *
    * This blocks the calling actor until the actor on which we call join() is terminated
    */
@@ -282,6 +297,7 @@ public:
   const char* get_property(std::string key);
   void set_property(std::string key, std::string value);
 
+#ifndef DOXYGEN
   /** @deprecated See Actor::create() */
   XBT_ATTRIB_DEPRECATED_v323("Please use Actor::create()") static ActorPtr createActor(
       const char* name, s4u::Host* host, std::function<void()> code)
@@ -373,6 +389,7 @@ public:
   {
     set_property(key, value);
   }
+#endif
 };
 
 /** @ingroup s4u_api
@@ -439,6 +456,7 @@ XBT_PUBLIC bool is_suspended();
 /** @brief kill the actor. */
 XBT_PUBLIC void exit();
 
+#ifndef DOXYGEN
 /** @deprecated Please use std::function<void(int, void*)> for first parameter */
 XBT_ATTRIB_DEPRECATED_v323("Please use std::function<void(int, void*)> for first parameter.") XBT_PUBLIC
     void on_exit(int_f_pvoid_pvoid_t fun, void* data);
@@ -466,6 +484,7 @@ XBT_ATTRIB_DEPRECATED_v323("Please use this_actor::is_suspended()") XBT_PUBLIC b
 XBT_ATTRIB_DEPRECATED_v323("Please use this_actor::on_exit()") XBT_PUBLIC void onExit(int_f_pvoid_pvoid_t fun, void* data);
 /** @deprecated See this_actor::exit() */
 XBT_ATTRIB_DEPRECATED_v324("Please use this_actor::exit()") XBT_PUBLIC void kill();
+#endif
 }
 
 /** @} */
diff --git a/include/simgrid/s4u/ConditionVariable.hpp b/include/simgrid/s4u/ConditionVariable.hpp
index 06037981ee..e2f5cce6c1 100644
--- a/include/simgrid/s4u/ConditionVariable.hpp
+++ b/include/simgrid/s4u/ConditionVariable.hpp
@@ -23,8 +23,10 @@ namespace s4u {
  */
 class XBT_PUBLIC ConditionVariable {
 private:
+#ifndef DOXYGEN
   friend kernel::activity::ConditionVariableImpl;
   smx_cond_t cond_;
+#endif
   explicit ConditionVariable(smx_cond_t cond) : cond_(cond) {}
 public:
   ConditionVariable(ConditionVariable const&) = delete;
diff --git a/include/simgrid/s4u/Engine.hpp b/include/simgrid/s4u/Engine.hpp
index fe486f403a..6bb6e896ca 100644
--- a/include/simgrid/s4u/Engine.hpp
+++ b/include/simgrid/s4u/Engine.hpp
@@ -84,23 +84,26 @@ public:
   void load_deployment(std::string deploy);
 
 protected:
-  friend s4u::Host;
-  friend s4u::Link;
-  friend s4u::Storage;
+#ifndef DOXYGEN
+  friend Host;
+  friend Link;
+  friend Storage;
   friend kernel::routing::NetPoint;
   friend kernel::routing::NetZoneImpl;
   friend kernel::resource::LinkImpl;
-  void host_register(std::string name, simgrid::s4u::Host* host);
+  void host_register(std::string name, Host* host);
   void host_unregister(std::string name);
-  void link_register(std::string name, simgrid::s4u::Link* link);
+  void link_register(std::string name, Link* link);
   void link_unregister(std::string name);
-  void storage_register(std::string name, simgrid::s4u::Storage* storage);
+  void storage_register(std::string name, Storage* storage);
   void storage_unregister(std::string name);
   void netpoint_register(simgrid::kernel::routing::NetPoint* card);
   void netpoint_unregister(simgrid::kernel::routing::NetPoint* card);
+#endif /*DOXYGEN*/
 
 public:
   size_t get_host_count();
+  /** @brief Returns the list of all hosts found in the platform */
   std::vector<Host*> get_all_hosts();
   std::vector<Host*> get_filtered_hosts(std::function<bool(Host*)> filter);
   simgrid::s4u::Host* host_by_name(std::string name);
diff --git a/include/simgrid/s4u/Exec.hpp b/include/simgrid/s4u/Exec.hpp
index b47ac41e9e..26af5d02e4 100644
--- a/include/simgrid/s4u/Exec.hpp
+++ b/include/simgrid/s4u/Exec.hpp
@@ -14,6 +14,11 @@
 namespace simgrid {
 namespace s4u {
 
+/** Computation #Activity, representing the asynchronous disk access.
+ *
+ * They are generated from simgrid::s4u::this_actor::exec_init() or simgrid::s4u::Host::execute().
+ */
+
 class XBT_PUBLIC Exec : public Activity {
   Exec() : Activity() {}
 public:
diff --git a/include/simgrid/s4u/Host.hpp b/include/simgrid/s4u/Host.hpp
index 164da062a7..26568e8b1d 100644
--- a/include/simgrid/s4u/Host.hpp
+++ b/include/simgrid/s4u/Host.hpp
@@ -35,8 +35,10 @@ namespace s4u {
  * and actors can retrieve the host on which they run using simgrid::s4u::Host::current().
  */
 class XBT_PUBLIC Host : public simgrid::xbt::Extendable<Host> {
+#ifndef DOXYGEN
   friend simgrid::vm::VMModel;            // Use the pimpl_cpu to compute the VM sharing
   friend simgrid::vm::VirtualMachineImpl; // creates the the pimpl_cpu
+#endif
 
 public:
   explicit Host(std::string name);
diff --git a/include/simgrid/s4u/Io.hpp b/include/simgrid/s4u/Io.hpp
index 17fd1f2605..72b5ea2296 100644
--- a/include/simgrid/s4u/Io.hpp
+++ b/include/simgrid/s4u/Io.hpp
@@ -15,6 +15,11 @@
 namespace simgrid {
 namespace s4u {
 
+/** I/O Activity, representing the asynchronous disk access.
+ *
+ * They are generated from simgrid::s4u::Storage::read() and simgrid::s4u::Storage::write().
+ */
+
 class XBT_PUBLIC Io : public Activity {
 public:
   enum class OpType { READ, WRITE };
diff --git a/include/simgrid/s4u/Link.hpp b/include/simgrid/s4u/Link.hpp
index bd4a84bac9..c6dd56d3d1 100644
--- a/include/simgrid/s4u/Link.hpp
+++ b/include/simgrid/s4u/Link.hpp
@@ -22,7 +22,9 @@ namespace simgrid {
 namespace s4u {
 /** @brief A Link represents the network facilities between [hosts](@ref simgrid::s4u::Host) */
 class XBT_PUBLIC Link : public simgrid::xbt::Extendable<Link> {
+#ifndef DOXYGEN
   friend simgrid::kernel::resource::LinkImpl;
+#endif
 
   // Links are created from the NetZone, and destroyed by their private implementation when the simulation ends
   explicit Link(kernel::resource::LinkImpl* pimpl) : pimpl_(pimpl) {}
diff --git a/include/simgrid/s4u/Mailbox.hpp b/include/simgrid/s4u/Mailbox.hpp
index 8b4267a86f..9e41dc1f63 100644
--- a/include/simgrid/s4u/Mailbox.hpp
+++ b/include/simgrid/s4u/Mailbox.hpp
@@ -102,8 +102,10 @@ namespace s4u {
  * @section s4u_mb_api The API
  */
 class XBT_PUBLIC Mailbox {
+#ifndef DOXYGEN
   friend Comm;
   friend simgrid::kernel::activity::MailboxImpl;
+#endif
 
   simgrid::kernel::activity::MailboxImpl* pimpl_;
 
diff --git a/include/simgrid/s4u/Mutex.hpp b/include/simgrid/s4u/Mutex.hpp
index b4df2e8b42..ae785f4841 100644
--- a/include/simgrid/s4u/Mutex.hpp
+++ b/include/simgrid/s4u/Mutex.hpp
@@ -29,8 +29,10 @@ class ConditionVariable;
  *
  */
 class XBT_PUBLIC Mutex {
+#ifndef DOXYGEN
   friend ConditionVariable;
   friend simgrid::kernel::activity::MutexImpl;
+#endif
   simgrid::kernel::activity::MutexImpl* pimpl_;
   explicit Mutex(simgrid::kernel::activity::MutexImpl* mutex) : pimpl_(mutex) {}
 
diff --git a/include/simgrid/s4u/NetZone.hpp b/include/simgrid/s4u/NetZone.hpp
index 8156699c38..ab145b9de4 100644
--- a/include/simgrid/s4u/NetZone.hpp
+++ b/include/simgrid/s4u/NetZone.hpp
@@ -25,7 +25,9 @@ namespace s4u {
  */
 class XBT_PUBLIC NetZone {
 protected:
+#ifndef DOXYGEN
   friend simgrid::kernel::routing::NetZoneImpl;
+#endif
 
   explicit NetZone(kernel::routing::NetZoneImpl* impl);
   ~NetZone();
diff --git a/include/simgrid/s4u/Storage.hpp b/include/simgrid/s4u/Storage.hpp
index b807c7fa3f..85005c1259 100644
--- a/include/simgrid/s4u/Storage.hpp
+++ b/include/simgrid/s4u/Storage.hpp
@@ -17,18 +17,21 @@
 #include <unordered_map>
 
 namespace simgrid {
-namespace xbt {
-extern template class XBT_PUBLIC Extendable<simgrid::s4u::Storage>;
-}
 namespace s4u {
 
+#ifndef DOXYGEN
 /** @deprecated Engine::get_all_storages() */
 XBT_ATTRIB_DEPRECATED_v322("Please use Engine::get_all_storages()") XBT_PUBLIC void getStorageList(std::map<std::string, Storage*>* whereTo);
+#endif
+
+/** Storage represent the disk resources, usually associated to a given host */
 
 class XBT_PUBLIC Storage : public simgrid::xbt::Extendable<Storage> {
+#ifndef DOXYGEN
   friend s4u::Engine;
   friend s4u::Io;
   friend simgrid::surf::StorageImpl;
+#endif /* DOXYGEN */
 
 public:
   explicit Storage(std::string name, surf::StorageImpl * pimpl);
diff --git a/src/s4u/s4u_Actor.cpp b/src/s4u/s4u_Actor.cpp
index b1f74569ab..c1d7128b9d 100644
--- a/src/s4u/s4u_Actor.cpp
+++ b/src/s4u/s4u_Actor.cpp
@@ -86,15 +86,6 @@ void Actor::on_exit(std::function<void(int, void*)> fun, void* data)
   simgrid::simix::simcall([this, fun, data] { SIMIX_process_on_exit(pimpl_, fun, data); });
 }
 
-/** @brief Moves the actor to another host
- *
- * If the actor is currently blocked on an execution activity, the activity is also
- * migrated to the new host. If it's blocked on another kind of activity, an error is
- * raised as the mandated code is not written yet. Please report that bug if you need it.
- *
- * Asynchronous activities started by the actor are not migrated automatically, so you have
- * to take care of this yourself (only you knows which ones should be migrated).
- */
 void Actor::migrate(Host* new_host)
 {
   s4u::Actor::on_migration_start(this);
diff --git a/src/s4u/s4u_Engine.cpp b/src/s4u/s4u_Engine.cpp
index afdc16fc64..3f8d5677e8 100644
--- a/src/s4u/s4u_Engine.cpp
+++ b/src/s4u/s4u_Engine.cpp
@@ -106,7 +106,6 @@ void Engine::getHostList(std::vector<Host*>* list)
     list->push_back(kv.second);
 }
 
-/** @brief Returns the list of all hosts found in the platform */
 std::vector<Host*> Engine::get_all_hosts()
 {
   std::vector<Host*> res;