From 1b238404f03d6ff882eff4267104225332fd8846 Mon Sep 17 00:00:00 2001 From: Martin Quinson Date: Wed, 18 Jul 2018 01:58:56 +0200 Subject: [PATCH 1/1] doxygen: rework the s4u header --- doc/doxygen/module-s4u.doc | 31 ++++++++++++++++--------------- 1 file changed, 16 insertions(+), 15 deletions(-) diff --git a/doc/doxygen/module-s4u.doc b/doc/doxygen/module-s4u.doc index 8b70f039ff..ac2d360367 100644 --- a/doc/doxygen/module-s4u.doc +++ b/doc/doxygen/module-s4u.doc @@ -2,20 +2,21 @@ @defgroup s4u_api S4U: Next generation SimGrid API @brief Future core API, mixing the full power of SimGrid to the power of C++. -The S4U API is near from its final state. Everything that you can do in -SimGrid should be possible in S4U and the missing pieces are seen as -bugs. - -@warning S4U is still evolving: v3.18 is a beta release. You - are really welcome to test it, but this API may change - between releases. This is however the way to go if you want - to create a new long-term project. If you want to play safe, - proceed to deprecated @ref MSG_API instead. - -Unsurprisingly, the S4U interface matches the concepts presented in -@ref starting_components "the introduction". You should read this page -first, to not get lost in the amount of classes provided here. Or you -could jump to the @ref s4u_examples directly if you prefer. +@b TLDR: The best documentation is the @ref s4u_examples + +Currently (v3.21), S4U is definitely the way to go for long-term +projects. It is feature complete, but may still evolve slightly in the +future releases. It can already be used to do everything that can be +done in SimGrid, but you may have to adapt your code in future +releases. When this happens, compiling your code will produce +deprecation warnings for 4 releases (one year) before the removal of +the old symbols. +If you want an API that will never ever evolve in the future, proceed +to the deprecated @ref MSG_API instead. + +The S4U interface matches the concepts presented in @ref +starting_components "the introduction". You should read this page +first, to not get lost in the amount of classes provided here. @section s4u_raii Memory Management of S4U objects @@ -33,7 +34,7 @@ Here is a little example: @code{cpp} void myFunc() { - simgrid::s4u::MutexPtr mutex = simgrid::s4u::Mutex::createMutex(); // Too bad we cannot use `new` here + simgrid::s4u::MutexPtr mutex = simgrid::s4u::Mutex::create(); // Too bad we cannot use `new` here mutex->lock(); // use the mutex as a simple reference // bla bla -- 2.20.1