From: Martin Quinson <martin.quinson@ens-rennes.fr>
Date: Sat, 21 Jan 2023 21:53:41 +0000 (+0100)
Subject: Add a section on errors and exceptions to the API documentation
X-Git-Tag: v3.34~601
X-Git-Url: http://bilbo.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/6c72fec7442cb2057b33f192c0dda51c0e440fbf

Add a section on errors and exceptions to the API documentation
---

diff --git a/ChangeLog b/ChangeLog
index 313343a98a..eed2b3e954 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -37,6 +37,7 @@ sthread:
 Documentation:
  - New section in the user guide on the provided performance models.
  - New section presenting some technical good practices for (potential) contributors.
+ - Add a section on errors and exceptions to the API documentation.
 
 Fixed bugs (FG#.. -> FramaGit bugs; FG!.. -> FG merge requests)
  (FG: issues on Framagit; GH: issues on GitHub)
diff --git a/docs/source/Doxyfile b/docs/source/Doxyfile
index c1746d98a4..db9ec7e666 100644
--- a/docs/source/Doxyfile
+++ b/docs/source/Doxyfile
@@ -9,6 +9,7 @@ INPUT                 += ../../include/simgrid/comm.h
 INPUT                 += ../../include/simgrid/cond.h
 INPUT                 += ../../include/simgrid/engine.h
 INPUT                 += ../../include/simgrid/exec.h
+INPUT                 += ../../include/simgrid/Exception.hpp
 INPUT                 += ../../include/simgrid/host.h
 INPUT                 += ../../src/s4u/s4u_Host.cpp
 #INPUT                 += ../../include/simgrid/instr.h
diff --git a/docs/source/app_s4u.rst b/docs/source/app_s4u.rst
index ff3a4f3e68..42bf128159 100644
--- a/docs/source/app_s4u.rst
+++ b/docs/source/app_s4u.rst
@@ -2765,6 +2765,55 @@ Locking
          .. doxygenfunction:: sg_sem_release(sg_sem_t sem)
          .. doxygenfunction:: sg_sem_would_block(const_sg_sem_t sem)
 
+===============
+Error reporting
+===============
+
+.. tabs::
+
+   .. group-tab:: C++
+
+      .. doxygenclass:: simgrid::Exception
+
+      The following exceptions denote a problem in the simulated platform, and it is often useful to catch them.
+
+      .. doxygenclass:: simgrid::CancelException
+      .. doxygenclass:: simgrid::HostFailureException
+      .. doxygenclass:: simgrid::NetworkFailureException
+      .. doxygenclass:: simgrid::StorageFailureException
+      .. doxygenclass:: simgrid::TimeoutException
+      .. doxygenclass:: simgrid::VmFailureException
+
+      The following errors denote a problem in the SimGrid tool itself. Most of the time, you should let these
+      exception go, so that the simulation stops. But you may want to catch them, for example when you launch
+      simgrid from a python notebook and want to handle the problem accordingly.
+
+      .. doxygenclass:: simgrid::AssertionError
+      .. doxygenclass:: simgrid::ParseError
+      .. doxygenclass:: simgrid::TracingError
+
+   .. group-tab:: Python
+
+      The following exceptions denote a problem in the simulated platform, and it is often useful to catch them.
+
+      .. autoclass:: simgrid.CancelException
+      .. autoclass:: simgrid.HostFailureException
+      .. autoclass:: simgrid.NetworkFailureException
+      .. autoclass:: simgrid.StorageFailureException
+      .. autoclass:: simgrid.TimeoutException
+      .. autoclass:: simgrid.VmFailureException
+
+      The following errors denote a problem in the SimGrid tool itself. Most of the time, you should let these
+      exception go, so that the simulation stops. But you may want to catch them, for example when you launch
+      simgrid from a python notebook and want to handle the problem accordingly.
+
+      .. autoclass:: simgrid.AssertionError
+
+   .. group-tab:: C
+
+      .. doxygenenum:: sg_error_t
+
+
 .. |hr| raw:: html
 
    <hr />
diff --git a/include/simgrid/Exception.hpp b/include/simgrid/Exception.hpp
index 23a71ceeb9..e580ea9117 100644
--- a/include/simgrid/Exception.hpp
+++ b/include/simgrid/Exception.hpp
@@ -3,14 +3,11 @@
 /* This program is free software; you can redistribute it and/or modify it
  * under the terms of the license (GNU LGPL) which comes with this package. */
 
+/* This file defines all possible exception that could occur in a SimGrid library. */
+
 #ifndef SIMGRID_EXCEPTIONS_HPP
 #define SIMGRID_EXCEPTIONS_HPP
 
-/** @file exception.hpp SimGrid-specific Exceptions
- *
- *  Defines all possible exception that could occur in a SimGrid library.
- */
-
 #include <xbt/backtrace.hpp>
 #include <xbt/ex.h>
 #include <xbt/string.hpp>
@@ -28,9 +25,7 @@ namespace xbt {
  *  Constitute the contextual information of where an exception was thrown
  *
  *  These tuples (__FILE__, __LINE__, __func__, backtrace, procname, pid)
- *  are best created with @ref XBT_THROW_POINT.
- *
- *  @ingroup XBT_ex
+ *  are best created with the macro XBT_THROW_POINT.
  */
 class ThrowPoint {
 public:
diff --git a/include/simgrid/forward.h b/include/simgrid/forward.h
index 9dafa1cc06..96bcd6ed19 100644
--- a/include/simgrid/forward.h
+++ b/include/simgrid/forward.h
@@ -316,13 +316,13 @@ typedef long long sg_offset_t;
 typedef long aid_t;
 
 typedef enum {
-  SG_OK,
-  SG_ERROR_CANCELED,
-  SG_ERROR_TIMEOUT,
-  SG_ERROR_HOST,
-  SG_ERROR_NETWORK,
-  SG_ERROR_STORAGE,
-  SG_ERROR_VM
+  SG_OK /** Code returned when no problem occured */,
+  SG_ERROR_CANCELED /** Code returned when something got canceled before completion */,
+  SG_ERROR_TIMEOUT /** Code returned when timeout elapsed */,
+  SG_ERROR_HOST /** Code returned when a host fails */,
+  SG_ERROR_NETWORK /** Code returned when a communication fails because of the network or because of the remote host */,
+  SG_ERROR_STORAGE /** Code returned when a storage fails */,
+  SG_ERROR_VM /** Code returned when a VM fails */
 } sg_error_t;
 
 XBT_PUBLIC int SMPI_is_inited();