Enhance documentation in Readme and Header

README.md

@@ -21,15 +21,15 @@
 < FOR A PARTICULAR PURPOSE. See GNU General Public License for details.           -->
 
 
-# Get started
+# Getting started
 
-If you have some basic tools installed (git, compiler and cmake) clone this repo:
+On Linux, Mac or Windows, if you have a basic C/C++ toolchain installed (git, compiler and cmake) clone this repo:
 
 ```
 git clone https://github.com/MattiaMontanari/openGJK.git
 ```
 
-followed by these commands:
+Then use these commands to build and run an example:
 
 ```
 cmake -E make_directory build
@@ -44,8 +44,17 @@ If you get no errors, the successfull output is:
 
 However, if you do get an error - any error - please file a bug! Support requests are welcome too.
 
-# Beyond getting started
+# Use OpenGJK in your project
 
-With the commands above you have built a demo example tha invokes the openGJK library. The library is statically linked and the distance between two bodies is computed and returned. 
+The best source to learn how to use OpenGJK are the examples. They are listed [here](https://www.mattiamontanari.com/opengjk/docs/examples/) for C, C#, Go, Matlab and Python. I aim to publish few more for Julia and Unity.
 
-To learn how to use this library in your project the best place to start is the demo. Look at `main.c` and the other examples. In `examples/c/CMakeLists.txt` you can find how simple is to link using CMake.
+Take a look at the `examples` folder in this repo and have fun. File a request if you wish to see more! 
+
+# Contribute
+
+You are very welcome to:
+
+- Create pull requests of any kind
+- Let me know if you are using this library and find it usefule
+- Open issues with request for support because they will help you and many others
+- Cite this repository ([a sweet GitHub feature](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files#about-citation-files)) or my paper: Montanari, M. et at, *Improving the GJK Algorithm for Faster and More Reliable Distance Queries Between Convex Objects* (2017). ACM Trans. Graph.

include/openGJK/openGJK.h

@@ -20,31 +20,52 @@
 // ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS  //
 // FOR A PARTICULAR PURPOSE. See GNU General Public License for details.          //
 
+/**
+ * @file openGJK.h
+ * @author Mattia Montanari
+ * @date 1 Jan 2022
+ * @brief Main interface of OpenGJK containing quick reference and API documentation.
+ *
+ * More extensive explanation of what the header
+ * @see http://google.com
+ */
+
 #ifndef OPENGJK_H__
 #define OPENGJK_H__
 
 #ifdef __cplusplus
-extern "C" {
+extern "C"
+{
 #endif
 
-/// @brief Use double as default precision
+/*! @brief Precision of floating-point numbers.
+ *
+ * Default is set to 64-bit (Double). Change this to quickly play around with 16- and 32-bit. */
 #define gkFloat double
 
-/// @brief Structure of a body
-typedef struct gkPolytope_ {
-  int numpoints;        // Number of points defining the body
-  gkFloat s[3];         // Support mapping computed last
-  gkFloat **coord;      // Points' coordinates
-} gkPolytope;
+  /*! @brief Data structure for convex polytopes.
+   *
+   * Polytopes are three-dimensional shapes and the GJK algorithm works directly on their convex-hull. However the convex-hull is never computed explicity, instead each GJK-iteraion employs a support function that has a cost linearly dependen on the number of points defining the polytope. */
+  typedef struct gkPolytope_
+  {
+    int numpoints;   /*!< Number of points defining the polytope. */
+    gkFloat s[3];    /*!< Furthest point retunred by the support function and updated at each GJK-iteration. For the first itearion this value is a guess - and this guess not irrelevant. */
+    gkFloat **coord; /*!< Coordinates of the points of the polytope. This is owned by user who manages and garbage-collects the memory for these coordinates. */
+  } gkPolytope;
 
-/// @brief Structure of the simplex
-typedef struct gkSimplex_ {
-  int nvrtx;            // Number of simplex's vertices
-  gkFloat vrtx[4][3];   // Coordinates of simplex's vertices
-} gkSimplex;
+  /*! @brief Data structure for simplex.
+   *
+   * The simplex is updated at each GJK-iteration. For the first itearion this value is a guess - and this guess not irrelevant. */
+  typedef struct gkSimplex_
+  {
+    int nvrtx;          /*!< Number of points defining the simplex. */
+    gkFloat vrtx[4][3]; /*!< Coordinates of the points of the simplex. */
+  } gkSimplex;
 
-/// @brief Uses the GJK algorithm to compute the minimum distance between two bodies
-gkFloat compute_minimum_distance(const gkPolytope p_, const gkPolytope q_, gkSimplex *s_);
+  /*! @brief Invoke the GJK algorithm to compute the minimum distance between two polytopes.
+   *
+   * The simplex has to be initialised prior the call to this function. */
+  gkFloat compute_minimum_distance(const gkPolytope p_, const gkPolytope q_, gkSimplex *s_);
 
 #ifdef __cplusplus
 }