Mark stuff as private.

README.md

@@ -69,11 +69,11 @@ servers with undefined backgrounds.
 
 Some hints:
 
-- Regard the header files in the `src`-directory as a documentation; we've
-  marked the parts that can be used as "public" there.
+- Regard the header files in the `src`-directory as a documentation; mrmailbox.h
+  is a good starting point
 
-- Functions ending with an underscore should be treated as library-private and
-  should normally not be used by the library user.
+- Headers may cointain headlines as "library-private" - stull following there
+  is not meant to be used by the library user.
 
 - For objects, C-structures are used.  If not mentioned otherwise, you can
   read the members here directly.

src/mrchat.c

@@ -110,7 +110,7 @@ static int mrchat_set_chat_from_stmt_(mrchat_t* ths, sqlite3_stmt* row)
 	ths->m_type      =                    sqlite3_column_int  (row, row_offset++);
 	ths->m_name      = safe_strdup((char*)sqlite3_column_text (row, row_offset++));
 	ths->m_lastMsg   = mrmsg_new(ths->m_mailbox);
-	mrmsg_set_msg_from_stmt(ths->m_lastMsg, row, row_offset);
+	mrmsg_set_from_stmt(ths->m_lastMsg, row, row_offset);
 
 	if( ths->m_name == NULL || ths->m_lastMsg == NULL || ths->m_lastMsg->m_msg == NULL ) {
 		return 0; /* error */
@@ -405,7 +405,7 @@ mrmsglist_t* mrchat_get_msgs_by_index(mrchat_t* ths, size_t index, size_t amount
 			while( sqlite3_step(stmt) == SQLITE_ROW )
 			{
 				mrmsg_t* msg = mrmsg_new(ths->m_mailbox);
-				if( msg && mrmsg_set_msg_from_stmt(msg, stmt, 0) ) {
+				if( msg && mrmsg_set_from_stmt(msg, stmt, 0) ) {
 					carray_add(ret->m_msgs, (void*)msg, NULL);
 				}
 			}

src/mrchat.h

@@ -47,28 +47,22 @@ extern "C" {
 
 typedef struct mrchat_t
 {
-	/* public read, unset strings are set to NULL */
 	uint32_t        m_id;
 	int             m_type;
-	char*           m_name;
-	mrmsg_t*        m_lastMsg;
-	mrmailbox_t*    m_mailbox;
-
-	/* private */
+	char*           m_name;    /* NULL if unset */
+	mrmsg_t*        m_lastMsg; /* NULL if unset */
+	mrmailbox_t*    m_mailbox; /* always set */
 	int             m_refcnt;
-
 } mrchat_t;
 
 
 typedef struct mrchatlist_t
 {
-	/* public read */
 	carray*      m_chats; /* contains mrchat_t objects */
 	mrmailbox_t* m_mailbox;
 } mrchatlist_t;
 
 
-/* public methods */
 void          mrchat_unref                 (mrchat_t*);
 mrmsg_t*      mrchat_get_last_msg          (mrchat_t*); /* result must be unref'd, as an alternative, you can use m_lastMsg directly */
 char*         mrchat_get_subtitle          (mrchat_t*); /* either the e-mail-address or the number of group members, the result must be free()'d! */
@@ -80,7 +74,8 @@ size_t        mrchatlist_get_cnt           (mrchatlist_t*);
 mrchat_t*     mrchatlist_get_chat          (mrchatlist_t*, size_t index); /* result must be unref'd, you can also use m_chats directly */
 
 
-/* private methods */
+/*** library-private **********************************************************/
+
 mrchat_t*     mrchat_new_                  (mrmailbox_t*); /* result must be unref'd */
 mrchat_t*     mrchat_ref_                  (mrchat_t*);
 void          mrchat_empty_                (mrchat_t*);

src/mrcontact.h

@@ -39,13 +39,10 @@ extern "C" {
 
 typedef struct mrcontact_t
 {
-	/* the data should be read only and are valid until the object is Release()'d.
-	unset strings are set to NULL. */
 	uint32_t            m_id;
 	char*               m_name;  /* != NULL, however, may be empty */
 	char*               m_email; /* != NULL */
 	mrmailbox_t*        m_mailbox;
-
 } mrcontact_t;
 
 
@@ -55,7 +52,9 @@ void         mrcontact_unref           (mrcontact_t*);
 int          mrcontact_load_from_db    (mrcontact_t*, uint32_t id);
 void         mrcontact_empty           (mrcontact_t*);
 
-/* private tools */
+
+/*** library-private **********************************************************/
+
 size_t       mr_get_contact_cnt_       (mrmailbox_t*); /* private, user shall use mrmailbox_get_contact_cnt() */
 
 

src/mrimap.h

@@ -33,7 +33,8 @@ extern "C" {
 #endif
 
 
-/* private IMAP thread command */
+/*** library-private **********************************************************/
+
 #define MR_THREAD_NOTALLOCATED  0
 #define MR_THREAD_INIT         10
 #define MR_THREAD_CONNECT      20
@@ -44,14 +45,12 @@ extern "C" {
 
 typedef struct mrimapthreadval_t
 {
-	/* private */
 	mailimap*    m_imap;
 } mrimapthreadval_t;
 
 
 typedef struct mrimap_t
 {
-	/* private */
 	mrmailbox_t*          m_mailbox;
 	const mrloginparam_t* m_loginParam;
 
@@ -65,7 +64,6 @@ typedef struct mrimap_t
 } mrimap_t;
 
 
-/* private */
 mrimap_t* mrimap_new               (mrmailbox_t*);
 void      mrimap_unref             (mrimap_t*);
 

src/mrimfparser.h

@@ -34,18 +34,17 @@ extern "C" {
 #endif
 
 
+/*** library-private **********************************************************/
+
 typedef struct mrimfparser_t
 {
-	/* private */
 	mrmailbox_t*  m_mailbox;
 } mrimfparser_t;
 
 
-/* private */
 mrimfparser_t* mrimfparser_new_    (mrmailbox_t* mailbox);
 void           mrimfparser_unref_  (mrimfparser_t*);
 
-/* private functions */
 /* Imf2Msg() takes an IMF, convers into one or more messages and stores them in the database.
 the function returns the number of new created messages. */
 int32_t        mrimfparser_imf2msg_(mrimfparser_t*, const char* imf_raw_not_terminated, size_t imf_raw_bytes);

src/mrlog.h

@@ -36,7 +36,6 @@ extern "C" {
 #include <sqlite3.h>
 
 
-/* public */
 void mr_log_error  (const char* msg);
 void mr_log_warning(const char* msg);
 void mr_log_info   (const char* msg);

src/mrmailbox.h

@@ -48,17 +48,12 @@ extern "C" {
 
 typedef struct mrmailbox_t
 {
-	/* public read */
 	mrloginparam_t* m_loginParam;
-
-	/* private */
 	mrimap_t*       m_imap;
 	mrsqlite3_t*    m_sql;
-
 } mrmailbox_t;
 
 
-/* public */
 mrmailbox_t*         mrmailbox_new                  ();
 void                 mrmailbox_unref                (mrmailbox_t*);
 
@@ -104,7 +99,9 @@ int32_t              mrmailbox_get_config_int       (mrmailbox_t*, const char* k
 char*                mrmailbox_get_db_file          (mrmailbox_t*); /* the returned string must be free()'d, returns NULL on errors or if no database is open */
 char*                mrmailbox_get_info             (mrmailbox_t*); /* multi-line output; the returned string must be free()'d, returns NULL on errors */
 
-/* private */
+
+/*** library-private **********************************************************/
+
 void                 mrmailbox_receive_imf_         (mrmailbox_t*, const char* imf, size_t imf_len); /* when fetching messages, this normally results in calls to ReceiveImf(). CAVE: ReceiveImf() may be called from within a working thread! */
 
 

src/mrmimeparser.h

@@ -34,12 +34,14 @@ extern "C" {
 #endif
 
 
+/*** library-private **********************************************************/
+
+
 #include "mrmsg.h"
 
 
 typedef struct mrmimepart_t
 {
-	/* private */
 	int                 m_type; /*one of MR_MSG_* */
 	char*               m_msg;
 	char*               m_msg_raw;
@@ -52,7 +54,7 @@ void          mrmimepart_unref  (mrmimepart_t*);
 
 typedef struct mrmimeparser_t
 {
-	/* private, data, read-only, must not be free()'d (it is free()'d when the MrMimeParser object gets destructed) */
+	/* data, read-only, must not be free()'d (it is free()'d when the MrMimeParser object gets destructed) */
 	carray*                m_parts; /*array of mrmimepart_t objects*/
 	struct mailmime*       m_mimeroot;
 	struct mailimf_fields* m_header;
@@ -60,18 +62,17 @@ typedef struct mrmimeparser_t
 } mrmimeparser_t;
 
 
-/* private */
 mrmimeparser_t* mrmimeparser_new_        ();
 void            mrmimeparser_unref_      (mrmimeparser_t*);
 void            mrmimeparser_empty_      (mrmimeparser_t*);
 
-/* private, The data returned from Parse() must not be freed (it is free()'d when the MrMimeParser object gets destructed)
+/* The data returned from Parse() must not be freed (it is free()'d when the MrMimeParser object gets destructed)
 Unless memory-allocation-errors occur, Parse() returns at least one empty part.
 (this is because we want to add even these message to our database to avoid reading them several times.
 of course, these empty messages are not added to any chat) */
 void            mrmimeparser_parse_      (mrmimeparser_t*, const char* body_not_terminated, size_t body_bytes);
 
-/* private, find out the mimetype - one of the MR_MIMETYPE_* constants */
+/* find out the mimetype - one of the MR_MIMETYPE_* constants */
 #define         MR_MIMETYPE_MP             0x100 /* eg. mixed */
 #define         MR_MIMETYPE_MP_ALTERNATIVE (MR_MIMETYPE_MP+1)
 #define         MR_MIMETYPE_MP_RELATED     (MR_MIMETYPE_MP+2)

src/mrmsg.c

@@ -86,7 +86,7 @@ void mrmsg_empty(mrmsg_t* ths)
 
 
 
-int mrmsg_set_msg_from_stmt(mrmsg_t* ths, sqlite3_stmt* row, int row_offset)
+int mrmsg_set_from_stmt(mrmsg_t* ths, sqlite3_stmt* row, int row_offset)
 {
 	mrmsg_empty(ths);
 

src/mrmsg.h

@@ -58,8 +58,6 @@ extern "C" {
 
 typedef struct mrmsg_t
 {
-	/* public read, unset strings are set to NULL. */
-
 	uint32_t      m_id;
 	uint32_t      m_from_id;   /* contact, 0 = self */
 	uint32_t      m_chat_id;   /* the chat, the message belongs to */
@@ -67,11 +65,10 @@ typedef struct mrmsg_t
 
 	int           m_type;      /* MR_MSG_* */
 	int           m_state;     /* MR_STATE_* etc. */
-	char*         m_msg;       /* meaning dedpends on m_type */
+	char*         m_msg;       /* meaning dedpends on m_type, NULL if unset */
 
 	mrmailbox_t*  m_mailbox;
 
-	/* private */
 	int           m_refcnt;
 } mrmsg_t;
 
@@ -82,19 +79,19 @@ typedef struct mrmsglist_t
 } mrmsglist_t;
 
 
-/* public */
 void         mrmsg_unref             (mrmsg_t*);
 
 #define      MR_UNWRAP 0x01
 char*        mrmsg_get_summary       (mrmsg_t*, long flags); /* the result should be free()'d */
 
 
-/* private */
+/*** library-private **********************************************************/
+
 mrmsg_t*     mrmsg_new               (mrmailbox_t*);
 mrmsg_t*     mrmsg_ref               (mrmsg_t*);
 void         mrmsg_empty             (mrmsg_t*);
 #define      MR_MSG_FIELDS " m.id,m.from_id,m.timestamp, m.type,m.state,m.msg " /* we use a define for easier string concatenation */
-int          mrmsg_set_msg_from_stmt (mrmsg_t*, sqlite3_stmt* row, int row_offset); /* row order is MR_MSG_FIELDS */
+int          mrmsg_set_from_stmt    (mrmsg_t*, sqlite3_stmt* row, int row_offset); /* row order is MR_MSG_FIELDS */
 
 mrmsglist_t* mrmsglist_new           (void);
 void         mrmsglist_unref         (mrmsglist_t*);

src/mrosnative.h

@@ -33,7 +33,8 @@ extern "C" {
 #endif
 
 
-/* private */
+/*** library-private **********************************************************/
+
 #if defined(ANDROID) || defined(__ANDROID__)
 #include <jni.h>
 void mrosnative_init_android  (JNIEnv* env);

src/mrsimplify.h

@@ -34,13 +34,14 @@ extern "C" {
 #endif
 
 
+/*** library-private **********************************************************/
+
 typedef struct mrsimplify_t
 {
-	/* private */
 	int dummy;
 } mrsimplify_t;
 
-/* private */
+
 mrsimplify_t* mrsimplify_new           ();
 void          mrsimplify_unref         (mrsimplify_t*);
 

src/mrsqlite3.h

@@ -33,13 +33,15 @@ extern "C" {
 #endif
 
 
+/*** library-private **********************************************************/
+
 #include <sqlite3.h>
 #include <libetpan/libetpan.h>
 #include <pthread.h>
 typedef struct mrmailbox_t mrmailbox_t; /*forward declaration*/
 
 
-/* predefined statements, private */
+/* predefined statements */
 enum
 {
 	 BEGIN_transaction = 0 /* must be first */
@@ -69,17 +71,16 @@ enum
 
 typedef struct mrsqlite3_t
 {
-	/* private, prepared statements - this is the favourite way for the caller to use SQLite */
+	/* prepared statements - this is the favourite way for the caller to use SQLite */
 	sqlite3_stmt* m_pd[PREDEFINED_CNT];
 
-	/* private, m_sqlite is the database given as dbfile to Open() */
+	/* m_sqlite is the database given as dbfile to Open() */
 	char*         m_dbfile; /* may be NULL */
 	sqlite3*      m_cobj;
 
-	/* private, helper for MrSqlite3Transaction */
+	/* helper for MrSqlite3Transaction */
 	int           m_transactionCount;
 
-	/* private */
 	mrmailbox_t*  m_mailbox;
 
 	/* the user must make sure, only one thread uses sqlite at the same time!
@@ -88,7 +89,6 @@ typedef struct mrsqlite3_t
 } mrsqlite3_t;
 
 
-/* private */
 mrsqlite3_t*  mrsqlite3_new              (mrmailbox_t*);
 void          mrsqlite3_unref            (mrsqlite3_t*);
 int           mrsqlite3_open             (mrsqlite3_t*, const char* dbfile);

src/mrtools.h

@@ -33,18 +33,17 @@ extern "C" {
 #endif
 
 
-/* public version */
 #define MR_VERSION_MAJOR    0
 #define MR_VERSION_MINOR    1
 #define MR_VERSION_REVISION 2
 
 
-/* public */
 char*   mr_get_version_str         (void);   /* the return value must be free()'d */
 char*   mr_timestamp_to_str        (time_t); /* the return value must be free()'d */
 
 
-/* private string pools */
+/*** library-private **********************************************************/
+
 char*   safe_strdup                (const char*); /* returns empty string if NULL is given, else same as strdup() */
 char*   mr_strlower                (const char*); /* the result must be free()'d */
 char*   mr_decode_header_string    (const char* in); /* the result must be free()'d */
@@ -54,7 +53,6 @@ char*   imap_modified_utf7_to_utf8 (const char *mbox, int change_spaces);
 char*   imap_utf8_to_modified_utf7 (const char *src, int change_spaces);
 
 
-/* private misc tools */
 #define MR_INVALID_TIMESTAMP       (-1)
 time_t  mr_timestamp_from_date     (struct mailimf_date_time * date_time); /* the result is UTC or MR_INVALID_TIMESTAMP */
 int     carray_search              (carray*, void* needle, unsigned int* indx); /* returns 1/0 and the index if `indx` is not NULL */