From c31dbe5e3400f2c87c5d09a85cf3a7315fe0694b Mon Sep 17 00:00:00 2001
From: Roker <roker@pep-project.org>
Date: Thu, 31 Aug 2017 12:55:26 +0200
Subject: [PATCH] =?UTF-8?q?create=20better=20documentation=20format.=20rem?=
 =?UTF-8?q?ove=20"=E2=80=93=E2=80=93"=20from=20separator=20names?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 html/interactive.js    | 67 ++++++++++++++++++++++++++----------------
 server/json-adapter.cc | 14 ++++-----
 2 files changed, 49 insertions(+), 32 deletions(-)

diff --git a/html/interactive.js b/html/interactive.js
index e88b37b..9973672 100644
--- a/html/interactive.js
+++ b/html/interactive.js
@@ -495,7 +495,7 @@ function init_pep_functions()
 	for(var i=0, len=pep_functions.length; i<len; ++i)
 	{
 		var f = pep_functions[i];
-		optionList += '<option' + (f.separator? ' disabled>':'>') + f.name + "</option>\n";
+		optionList += '<option' + (f.separator? ' disabled> —— ':'>') + f.name + "</option>\n";
 	}
 	document.getElementById("fn_name").innerHTML = optionList;
 	document.getElementById("spn_version").innerHTML = "version: " + server_version;
@@ -504,27 +504,36 @@ function init_pep_functions()
 
 function create_doc()
 {
-	var table_def = {
-		html : {    start : '<table class="dtable">',       end: '</table>\n',
-				header : '<tr><th>Function name</th><th>Return Type</th><th>Parameters</th></tr>\n',
-				line_start  : '<tr>', line_end  : '</tr>\n',
-				cell_start : '<td>' ,  cell_end : '</td>'
+	var format_def = {
+		html : {   section_start : '<h3>' ,    section_end : '</h3>\n',
+				subsection_start : '<h4>' , subsection_end : '</h4>\n',
+				b_start : '<b>', b_end : '</b>',
+				table_start  : '<table class="dtable">', table_end: '</table>\n',
+				table_header : '<tr><th>Function name</th><th>Return Type</th><th>Parameters</th></tr>\n',
+				line_start : '<tr>', line_end : '</tr>\n',
+				cell_start : '<td>', cell_end : '</td>'
 				},
-		md :   { start: '', end: '\n',
-				header : '| Function name | Return Type | Parameters |\n' +
-				         '|---------------|-------------|------------|\n',
-				line_start : '', line_end : '|\n',
+		md :   {   section_start : '### '  ,    section_end : ' ###\n',
+				subsection_start : '#### ' , subsection_end : ' ####\n',
+				b_start : ' **', b_end : '** ',
+				table_start : '', table_end: '\n',
+				table_header: '| Function name | Return Type | Parameters |\n' +
+				              '|---------------|-------------|------------|\n',
+				line_start : ''  , line_end: '|\n',
 				cell_start : '| ', cell_end: ' '
 				},
-		trac : { start: '', end: '\n',
-				header : '||= Function name =||= Return Type =||= Parameters =||\n',
-				line_start : '|', line_end : '|\n',
-				cell_start : '| ', cell_end: ' |'
+		trac : {   section_start : '=== '  ,    section_end : ' ===\n',
+				subsection_start : '==== ' , subsection_end : ' ====\n',
+				b_start : ' **', b_end : '** ',
+				table_start : ''  , table_end: '\n',
+				table_header: '||= Function name =||= Return Type =||= Parameters =||\n',
+				line_start : '|' , line_end : '|\n',
+				cell_start : '| ', cell_end : ' |'
 				}
 	};
 	
 	var format_name = document.getElementById('doc_format').value;
-	var format_def  = table_def[format_name];
+	var fd  = format_def[format_name];
 	var output = ""; 
 	
 	for(var i=0, len=pep_functions.length; i<len; ++i)
@@ -532,12 +541,17 @@ function create_doc()
 		var f = pep_functions[i];
 		if(f.separator)
 		{
-			output += format_def.end + "\n" + f.name + "\n" + format_def.start + format_def.header;
+			if(output.length > 0)
+			{
+				output += fd.table_end + "\n";
+			}
+			output += fd.subsection_start + f.name + fd.subsection_end
+			 + fd.table_start + fd.table_header;
 		}else{
-			output += format_def.line_start
-				+ format_def.cell_start + f.name + format_def.cell_end
-				+ format_def.cell_start + f["return"] + format_def.cell_end
-				+ format_def.cell_start ;
+			output += fd.line_start
+				+ fd.cell_start + f.name + fd.cell_end
+				+ fd.cell_start + f["return"] + fd.cell_end
+				+ fd.cell_start ;
 			
 			for( var p=0, plen = f.params.length; p<plen; ++p)
 			{
@@ -551,16 +565,19 @@ function create_doc()
 				}
 			}
 			
-			output += format_def.cell_end + format_def.line_end;
+			output += fd.cell_end + fd.line_end;
 			
 		}
 	}
 	
+	output =
+		fd.section_start + 'Function reference for the p≡p JSON Server Adapter. Version “' + server_version + '”' + fd.section_end
+		+ 'Output parameters are denoted by a ' + fd.b_start + '⇑' + fd.b_end + ', '
+		+ 'InOut parameters are denoted by a ' + fd.b_start + '⇕' + fd.b_end + ' after the parameter type.\n\n'
+		+ output + fd.table_end;
+
 	if(format_name != "html")
 		output = "<pre>" + output + "\n</pre>";
 	
-	document.getElementById("doc_out").innerHTML = 
-		'<h4>Function reference for the p≡p JSON Server Adapter. Version “' + server_version + '”</h4>'
-		+ 'Output parameters are denoted by a <b>⇑</b>, InOut parameters are denoted by a <b>⇕</b> after the parameter type.<br>'
-		+ output;
+	document.getElementById("doc_out").innerHTML = output;
 }
diff --git a/server/json-adapter.cc b/server/json-adapter.cc
index 299636e..fb5ff41 100644
--- a/server/json-adapter.cc
+++ b/server/json-adapter.cc
@@ -200,7 +200,7 @@ PEP_STATUS MIME_decrypt_message_ex(
 // these are the pEp functions that are callable by the client
 const FunctionMap functions = {
 		// from message_api.h
-		FP( "—— Message API ——", new Separator ),
+		FP( "Message API", new Separator ),
 		FP( "MIME_encrypt_message", new Func<PEP_STATUS, In<PEP_SESSION, false>, In<const char*>, In<size_t>, In<stringlist_t*>,
 			Out<char*>, In<PEP_enc_format>, In<PEP_encrypt_flags_t>>( &MIME_encrypt_message ) ),
 		FP( "MIME_encrypt_message_for_self", new Func<PEP_STATUS, In<PEP_SESSION, false>, In<pEp_identity*>, In<const char*>, In<size_t>,
@@ -227,7 +227,7 @@ const FunctionMap functions = {
 		FP( "identity_rating" , new Func<PEP_STATUS, In<PEP_SESSION,false>, In<pEp_identity*>, Out<PEP_rating>>( &identity_rating) ),
 		FP( "get_gpg_path",    new Func<PEP_STATUS, Out<const char*>>(&get_gpg_path) ),
 		
-		FP( "—— pEp Engine Core API ——", new Separator),
+		FP( "pEp Engine Core API", new Separator),
 		FP( "log_event",  new Func<PEP_STATUS, In<PEP_SESSION,false>, In<const char*>, In<const char*>, In<const char*>, In<const char*>>( &log_event) ),
 		FP( "get_trustwords", new Func<PEP_STATUS, In<PEP_SESSION,false>, In<const pEp_identity*>, In<const pEp_identity*>, In<Language>, Out<char*>, Out<size_t>, In<bool>>( &get_trustwords) ),
 		FP( "get_languagelist", new Func<PEP_STATUS, In<PEP_SESSION,false>, Out<char*>>( &get_languagelist) ),
@@ -236,7 +236,7 @@ const FunctionMap functions = {
 		FP( "config_passive_mode", new Func<void, In<PEP_SESSION,false>, In<bool>>( &config_passive_mode) ),
 		FP( "config_unencrypted_subject", new Func<void, In<PEP_SESSION,false>, In<bool>>( &config_unencrypted_subject) ),
 		
-		FP( "—— Identity Management API ——", new Separator),
+		FP( "Identity Management API", new Separator),
 		FP( "get_identity"       , new Func<PEP_STATUS, In<PEP_SESSION,false>, In<const char*>, In<const char*>, Out<pEp_identity*>>( &get_identity) ),
 		FP( "set_identity"       , new Func<PEP_STATUS, In<PEP_SESSION,false>, In<pEp_identity*>> ( &set_identity) ),
 		FP( "mark_as_comprimized", new Func<PEP_STATUS, In<PEP_SESSION,false>, In<const char*>> ( &mark_as_compromized) ),
@@ -245,7 +245,7 @@ const FunctionMap functions = {
 		FP( "set_identity_flags", new Func<PEP_STATUS, In<PEP_SESSION,false>, In<pEp_identity*>, In<identity_flags_t>>( &set_identity_flags) ),
 		FP( "unset_identity_flags", new Func<PEP_STATUS, In<PEP_SESSION,false>, In<pEp_identity*>, In<identity_flags_t>>( &unset_identity_flags) ),
 		
-		FP( "—— Low level Key Management API ——", new Separator),
+		FP( "Low level Key Management API", new Separator),
 		FP( "generate_keypair", new Func<PEP_STATUS, In<PEP_SESSION,false>, InOut<pEp_identity*>> ( &generate_keypair) ),
 		FP( "delete_keypair", new Func<PEP_STATUS, In<PEP_SESSION,false>, In<const char*>> ( &delete_keypair) ),
 		FP( "import_key"    , new Func<PEP_STATUS, In<PEP_SESSION,false>, In<const char*>, In<std::size_t>, Out<identity_list*>> ( &import_key) ),
@@ -268,20 +268,20 @@ const FunctionMap functions = {
 		FP( "revoke"        , new Func<PEP_STATUS, In<PEP_SESSION,false>, In<const char*>, In<const char*>> ( &revoke_key) ),
 		FP( "key_expired"   , new Func<PEP_STATUS, In<PEP_SESSION,false>, In<const char*>, In<time_t>, Out<bool>> ( &key_expired) ),
 		
-		FP( "—— from blacklist.h & OpenPGP_compat.h ——", new Separator),
+		FP( "from blacklist.h & OpenPGP_compat.h", new Separator),
 		FP( "blacklist_add"   , new Func<PEP_STATUS, In<PEP_SESSION,false>, In<const char*>> ( &blacklist_add) ),
 		FP( "blacklist_delete", new Func<PEP_STATUS, In<PEP_SESSION,false>, In<const char*>> ( &blacklist_delete) ),
 		FP( "blacklist_is_listed", new Func<PEP_STATUS, In<PEP_SESSION,false>, In<const char*>, Out<bool>> ( &blacklist_is_listed) ),
 		FP( "blacklist_retrieve" , new Func<PEP_STATUS, In<PEP_SESSION,false>, Out<stringlist_t*>> ( &blacklist_retrieve) ),
 		FP( "OpenPGP_list_keyinfo", new Func<PEP_STATUS, In<PEP_SESSION,false>, In<const char*>, Out<stringpair_list_t*>> ( &OpenPGP_list_keyinfo) ),
 		
-		FP( "-- Event Listener & Results", new Separator ),
+		FP( "Event Listener & Results", new Separator ),
 		FP( "registerEventListener"  , new Func<PEP_STATUS, In<Context*, false>, In<std::string>, In<unsigned>, In<std::string>> ( &registerEventListener) ),
 		FP( "unregisterEventListener", new Func<PEP_STATUS, In<Context*, false>, In<std::string>, In<unsigned>, In<std::string>> ( &unregisterEventListener) ),
 		FP( "deliverHandshakeResult" , new Func<PEP_STATUS, In<PEP_SESSION,false>, In<pEp_identity*>, In<sync_handshake_result>> (&deliverHandshakeResult) ),
 		
 		// my own example function that does something useful. :-)
-		FP( "—— Other ——", new Separator ),
+		FP( "Other", new Separator ),
 		FP( "version",     new Func<std::string>( &JsonAdapter::version ) ),
 		FP( "apiVersion",  new Func<unsigned>   ( &JsonAdapter::apiVersion ) ),
 		FP( "getGpgEnvironment", new Func<GpgEnvironment>( &getGpgEnvironment ) ),