further improvement to the doxygen doc

diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst
index 8c5a6e8..cf25747 100644 (file)
--- a/docs/source/app_s4u.rst
+++ b/docs/source/app_s4u.rst
@@ -1200,11 +1200,17 @@ Querying info
       .. doxygenfunction:: simgrid::s4u::Disk::set_property(const std::string &, const std::string &value)
       .. doxygenfunction:: simgrid::s4u::Disk::set_sharing_policy
 
+      .. doxygenenum:: simgrid::s4u::Disk::Operation
+      .. doxygenenum:: simgrid::s4u::Disk::SharingPolicy
+
    .. group-tab:: Python
 
       .. autoattribute:: simgrid.Disk.name
       .. automethod:: simgrid.Disk.set_sharing_policy
 
+      .. autoclass:: simgrid.Disk.Operation
+      .. autoclass:: simgrid.Disk.SharingPolicy
+
 I/O operations
 --------------
 
@@ -1611,52 +1617,70 @@ Querying info
 
    .. group-tab:: C++
 
-      .. doxygenfunction:: simgrid::s4u::Link::get_bandwidth() const
       .. doxygenfunction:: simgrid::s4u::Link::get_cname() const
-      .. doxygenfunction:: simgrid::s4u::Link::get_latency() const
       .. doxygenfunction:: simgrid::s4u::Link::get_name() const
-      .. doxygenfunction:: simgrid::s4u::Link::get_sharing_policy() const
-      .. doxygenfunction:: simgrid::s4u::Link::get_concurrency_limit() const
       .. doxygenfunction:: simgrid::s4u::Link::get_load() const
       .. doxygenfunction:: simgrid::s4u::Link::is_used() const
 
    .. group-tab:: Python
 
-      .. autoattribute:: simgrid.Link.bandwidth
-      .. autoattribute:: simgrid.Link.latency
+      .. autoattribute:: simgrid.Link.name
 
    .. group-tab:: C
 
-      .. doxygenfunction:: sg_link_get_bandwidth(const_sg_link_t link)
-      .. doxygenfunction:: sg_link_get_latency(const_sg_link_t link)
       .. doxygenfunction:: sg_link_get_name(const_sg_link_t link)
       .. doxygenfunction:: sg_link_is_shared(const_sg_link_t link)
 
-Modifying characteristics
--------------------------
+Performance
+-----------
 
 .. tabs::
 
    .. group-tab:: C++
 
+      .. doxygenfunction:: simgrid::s4u::Link::get_bandwidth() const
+      .. doxygenfunction:: simgrid::s4u::Link::get_latency() const
       .. doxygenfunction:: simgrid::s4u::Link::set_bandwidth(double value)
       .. doxygenfunction:: simgrid::s4u::Link::set_latency(double value)
       .. doxygenfunction:: simgrid::s4u::Link::set_latency(const std::string& value)
-      .. doxygenfunction:: simgrid::s4u::Link::set_concurrency_limit(int limit)
-      .. doxygenfunction:: simgrid::s4u::Link::set_sharing_policy
 
    .. group-tab:: Python
 
+      .. autoattribute:: simgrid.Link.bandwidth
+      .. autoattribute:: simgrid.Link.latency
       .. automethod:: simgrid.Link.set_bandwidth
       .. automethod:: simgrid.Link.set_latency
-      .. automethod:: simgrid.Link.set_concurrency_limit
-      .. automethod:: simgrid.Link.set_sharing_policy
 
    .. group-tab:: C
 
+      .. doxygenfunction:: sg_link_get_bandwidth(const_sg_link_t link)
+      .. doxygenfunction:: sg_link_get_latency(const_sg_link_t link)
       .. doxygenfunction:: sg_link_set_bandwidth(sg_link_t link, double value)
       .. doxygenfunction:: sg_link_set_latency(sg_link_t link, double value)
 
+Model policy
+------------
+
+.. tabs::
+
+   .. group-tab:: C++
+
+      .. doxygenenum:: simgrid::s4u::Link::SharingPolicy
+
+      .. doxygenfunction:: simgrid::s4u::Link::get_sharing_policy() const
+      .. doxygenfunction:: simgrid::s4u::Link::set_sharing_policy
+         
+      .. doxygenfunction:: simgrid::s4u::Link::get_concurrency_limit() const
+      .. doxygenfunction:: simgrid::s4u::Link::set_concurrency_limit(int limit)
+
+   .. group-tab:: Python
+
+      .. automethod:: simgrid.Link.set_concurrency_limit
+      .. automethod:: simgrid.Link.set_sharing_policy
+
+   .. group-tab:: C
+
+
 User data and properties
 ------------------------
 

diff --git a/include/simgrid/s4u/Link.hpp b/include/simgrid/s4u/Link.hpp
index c79ca46..c2ac18e 100644 (file)
--- a/include/simgrid/s4u/Link.hpp
+++ b/include/simgrid/s4u/Link.hpp
@@ -45,7 +45,21 @@ protected:
 #endif
 
 public:
-  enum class SharingPolicy { NONLINEAR = 4, WIFI = 3, SPLITDUPLEX = 2, SHARED = 1, FATPIPE = 0 };
+  /** Specifies how a given link is shared between concurrent communications */
+  enum class SharingPolicy {
+    /// This policy takes a callback that specifies the maximal capacity as a function of the number of usage. See the
+    /// examples with 'degradation' in their name.
+    NONLINEAR = 4,
+    /// Pseudo-sharing policy requesting wifi-specific sharing.
+    WIFI = 3,
+    /// Each link is split in 2, UP and DOWN, one per direction. These links are SHARED.
+    SPLITDUPLEX = 2,
+    /// The bandwidth is shared between all comms using that link, regardless of their direction.
+    SHARED = 1,
+    /// Each comm can use the link fully, with no sharing (only a maximum). This is intended to represent the backbone
+    /// links that cannot be saturated by concurrent links, but have a maximal bandwidth.
+    FATPIPE = 0
+  };
 
   kernel::resource::StandardLinkImpl* get_impl() const;
 

diff --git a/src/bindings/python/simgrid_python.cpp b/src/bindings/python/simgrid_python.cpp
index 8dd178a..41e8646 100644 (file)
--- a/src/bindings/python/simgrid_python.cpp
+++ b/src/bindings/python/simgrid_python.cpp
@@ -571,11 +571,17 @@ PYBIND11_MODULE(simgrid, m)
           "__repr__", [](const Link* l) { return "Link(" + l->get_name() + ")"; },
           "Textual representation of the Link");
   py::enum_<Link::SharingPolicy>(link, "SharingPolicy")
-      .value("NONLINEAR", Link::SharingPolicy::NONLINEAR)
-      .value("WIFI", Link::SharingPolicy::WIFI)
-      .value("SPLITDUPLEX", Link::SharingPolicy::SPLITDUPLEX)
-      .value("SHARED", Link::SharingPolicy::SHARED)
-      .value("FATPIPE", Link::SharingPolicy::FATPIPE);
+      .value("NONLINEAR", Link::SharingPolicy::NONLINEAR,
+             "This policy takes a callback that specifies the maximal capacity as a function of the number of usage. "
+             "See the examples with 'degradation' in their name.")
+      .value("WIFI", Link::SharingPolicy::WIFI, "Pseudo-sharing policy requesting wifi-specific sharing.")
+      .value("SPLITDUPLEX", Link::SharingPolicy::SPLITDUPLEX,
+             "Each link is split in 2, UP and DOWN, one per direction. These links are SHARED.")
+      .value("SHARED", Link::SharingPolicy::SHARED,
+             "The bandwidth is shared between all comms using that link, regardless of their direction.")
+      .value("FATPIPE", Link::SharingPolicy::FATPIPE,
+             "Each comm can use the link fully, with no sharing (only a maximum). This is intended to represent the "
+             "backbone links that cannot be saturated by concurrent links, but have a maximal bandwidth.");
 
   /* Class LinkInRoute */
   py::class_<simgrid::s4u::LinkInRoute> linkinroute(m, "LinkInRoute", "Abstraction to add link in routes");