Update api

api.md

@@ -4,8 +4,8 @@ exhale Wiki :: Application Programming Interface (API)
 The following is a description of the public C/C++ functions exported by the exhale library for use by external applications, representing exhale's application programming interface (API). These functions are described in the order in which they must be called. The exact function and *ExhaleEncAPI* class prototypes are declared in the header file [exhaleDecl.h](https://gitlab.com/ecodis/exhale/blob/master/include/exhaleDecl.h) provided in the `include` subdirectory of the exhale source distribution.
 
 
-ExhaleEncAPI* exhaleCreate( )
------------------------------
+ExhaleEncAPI* exhaleCreate()
+----------------------------
 
 **C declaration**
 
@@ -13,15 +13,19 @@ ExhaleEncAPI* `exhaleCreate`(int32_t* const inputPcmData, unsigned char* const o
 
 **C++ class declaration**
 
-*none*
+*none (class constructor)*
 
 **Purpose**
 
 create an *ExhaleEncAPI* object and return a pointer to it
 
+**Return value**
 
-unsigned exhaleInitEncoder( )
------------------------------
+the pointer to the newly created *ExhaleEncAPI* object
+
+
+unsigned exhaleInitEncoder()
+----------------------------
 
 **C declaration**
 
@@ -33,11 +37,15 @@ unsigned ExhaleEncAPI::`initEncoder`(unsigned char* const audioConfigBuffer, uin
 
 **Purpose**
 
-initialize an *ExhaleEncAPI* object for encoding
+initialize an *ExhaleEncAPI* object for encoding and allocate necessary object memory
+
+**Return value**
+
+zero (0) upon success, or nonzero (1-255 or 65535) in case of an error or if the *exhaleEnc* pointer is `NULL`
 
 
-unsigned exhaleEncodeLookahead( )
----------------------------------
+unsigned exhaleEncodeLookahead()
+--------------------------------
 
 **C declaration**
 
@@ -45,15 +53,19 @@ unsigned `exhaleEncodeLookahead`(ExhaleEncAPI* exhaleEnc);
 
 **C++ class declaration**
 
-unsigned ExhaleEncAPI::`encodeLookahead`();
+unsigned ExhaleEncAPI::`encodeLookahead`( );
 
 **Purpose**
 
 encode the first (lookahead) frame with an *ExhaleEncAPI* object
 
+**Return value**
 
-unsigned exhaleEncodeFrame( )
------------------------------
+the byte-size (2 < *b* < 65535) of the AU upon success, or nonzero (1, 2 or 65535) in case of an error or if the *exhaleEnc* pointer is `NULL`
+
+
+unsigned exhaleEncodeFrame()
+----------------------------
 
 **C declaration**
 
@@ -61,15 +73,19 @@ unsigned `exhaleEncodeFrame`(ExhaleEncAPI* exhaleEnc);
 
 **C++ class declaration**
 
-unsigned ExhaleEncAPI::`encodeFrame`();
+unsigned ExhaleEncAPI::`encodeFrame`( );
 
 **Purpose**
 
-encode a regular frame with an *ExhaleEncAPI* object
+encode a regular PCM audio frame with an *ExhaleEncAPI* object
+
+**Return value**
+
+the byte-size (2 < *b* < 65535) of the AU upon success, or nonzero (1, 2 or 65535) in case of an error or if the *exhaleEnc* pointer is `NULL`
 
 
-unsigned exhaleDelete( )
-------------------------
+unsigned exhaleDelete()
+-----------------------
 
 **C declaration**
 
@@ -77,8 +93,13 @@ unsigned `exhaleDelete`(ExhaleEncAPI* exhaleEnc);
 
 **C++ class declaration**
 
-ExhaleEncAPI::`~ExhaleEncAPI`(); *(class destructor)*
+ExhaleEncAPI::`~ExhaleEncAPI`( ); *(class destructor)*
 
 **Purpose**
 
-free all dynamic memory allocated by an *ExhaleEncAPI* object
+free all dynamic memory allocated by an *ExhaleEncAPI* object. After calling this function, the *exhaleEnc* pointer can be set to `NULL`.
+
+
+**Return value**
+
+zero (0) upon success, or nonzero (65535) if the *exhaleEnc* pointer is `NULL`