Correctly document the functions

[claucece]

A style format for how to manually document functionality is needed.

For the actual documentation of all the functionality, we need the whole 'Full OTRv4 flow #2' done and issue #72 done.

[claucece]

Let's document with this structure:

For functions:

/**
  * @brief Define what the function does in summary
  *  
  *  @params 
  *  [out] the out parameter
  *  [in] the in parameter
  *
  * @return (if present)
  *
  * @details Details around this function if any
  *
  * @warning
  * Any warning
 **/

For structures:

** 
  * @brief A summary of what is this structure
  * 
  *  [type] 
**/

@giovaneliberato

[olabini]

One open question. This proposal uses [out] and [in] parameters. I used a different style, using [bla] where bla is the name, and not specifying whether it's an out or in parameter (I expected that to be clear from the description of the parameter). We should decide what form to use.

[claucece]

I guess things are already documented that way, so:

/**
  * @brief Define what the function does in summary
  *  
  *  @params 
  *  [bla1] the bla1 parameter
  *  [bla2] the bla2 parameter
  *
  * @return (if present)
  *
  * @details Details around this function if any
  *
  * @warning
  * Any warning
 **/

should be fine. :)

[olabini]

Great, thanks! =)

[giovaneliberato]

Agreed!

[olabini]

This depends on #6