init: Clarify the need to call ssh_{init, finalize}()

When libssh is statically linked, it is necessary to explicitly call
ssh_init() before calling any other provided API.  It is also necessary
to call ssh_finalize() before exiting to free allocated resources.

Fixes T222

Signed-off-by: Anderson Toshiyuki Sasaki <ansasaki@redhat.com>
Reviewed-by: Andreas Schneider <asn@cryptomilk.org>

src/init.c

@@ -135,14 +135,20 @@ void libssh_constructor(void)
 /**
  * @brief Initialize global cryptographic data structures.
  *
- * Since version 0.8.0, it is not necessary to call this function on systems
+ * Since version 0.8.0, when libssh is dynamically linked, it is not necessary
- * which are fully supported with regards to threading (that is, system with
+ * to call this function on systems which are fully supported with regards to
- * pthreads available).
+ * threading (that is, system with pthreads available).
+ *
+ * If libssh is statically linked, it is necessary to explicitly call ssh_init()
+ * before calling any other provided API, and it is necessary to explicitly call
+ * ssh_finalize() to free the allocated resources before exiting.
  *
  * If the library is already initialized, increments the _ssh_initialized
  * counter and return the error code cached in _ssh_init_ret.
  *
  * @returns             SSH_OK on success, SSH_ERROR if an error occurred.
+ *
+ * @see ssh_finalize()
  */
 int ssh_init(void) {
     return _ssh_init(0);
@@ -202,8 +208,13 @@ void libssh_destructor(void)
 /**
  * @brief Finalize and cleanup all libssh and cryptographic data structures.
  *
- * Since version 0.8.0, it is not necessary to call this function, since it is
+ * Since version 0.8.0, when libssh is dynamically linked, it is not necessary
- * automatically called when the library is unloaded.
+ * to call this function, since it is automatically called when the library is
+ * unloaded.
+ *
+ * If libssh is statically linked, it is necessary to explicitly call ssh_init()
+ * before calling any other provided API, and it is necessary to explicitly call
+ * ssh_finalize() to free the allocated resources before exiting.
  *
  * If ssh_init() is called explicitly, then ssh_finalize() must be called
  * explicitly.
@@ -211,9 +222,9 @@ void libssh_destructor(void)
  * When called, decrements the counter _ssh_initialized. If the counter reaches
  * zero, then the libssh and cryptographic data structures are cleaned up.
  *
- * @returns             0 on succes, -1 if an error occured.
+ * @returns             0 on success, -1 if an error occurred.
  *
- @returns 0 otherwise
+ * @see ssh_init()
  */
 int ssh_finalize(void) {
     return _ssh_finalize(0);