From: Martin Quinson <martin.quinson@loria.fr>
Date: Tue, 17 Jul 2018 23:58:56 +0000 (+0200)
Subject: doxygen: rework the s4u header
X-Git-Tag: v3_21~408
X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/1b238404f03d6ff882eff4267104225332fd8846?hp=d8eb62b207b566949a0d9ce649a7b21e226b9168;ds=sidebyside

doxygen: rework the s4u header
---

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 <b>S4U is still evolving: v3.18 is a beta release</b>. 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