- * As for any S4U object, Semaphores are using the @ref s4u_raii "RAII idiom" for memory management.
- * Use createSemaphore() to get a ::SemaphorePtr to a newly created semaphore
- * and only manipulate ::SemaphorePtr.
+ * An example is available in Section :ref:`s4u_ex_IPC`.
+ *
+ * As for any S4U object, you can use the :ref:`RAII idiom <s4u_raii>` for memory management of semaphores.
+ * Use :cpp:func:`create() <simgrid::s4u::Mutex::create()>` to get a :cpp:type:`simgrid::s4u::SemaphorePtr` to a newly
+ * created semaphore, that will get automatically freed when the variable goes out of scope.
+ * @endrst