# HG changeset patch
# User Rob Hoes <rob.hoes@xxxxxxxxxx>
# Date 1258733582 0
# Node ID d6396c0904fc68123455e5a4738c7d7b096cce69
# Parent  2b994a4fda1ef278a1291562f9867b360862ac8f
[ocamldoc] Information on the completeness of the documentation

This patch introduces percentages at modules and components on the ocamldoc pages, indicating how "complete" the documentation is. Completeness is defined as the percentage of the elements (modules, functions, types, ...) that have a proper ocamldoc description. I'll only remove these statistics when there are all "100%" ;)

The xapi toolstack docs are now 12% complete!

Note that even though many descriptions are still missing, the structure of the modules and their dependencies can already be explored.

Signed-off-by: Rob Hoes <rob.hoes@xxxxxxxxxx>

diff -r 2b994a4fda1e -r d6396c0904fc ocaml/doc/ocamldoc.js
--- a/ocaml/doc/ocamldoc.js	Fri Nov 20 16:13:02 2009 +0000
+++ b/ocaml/doc/ocamldoc.js	Fri Nov 20 16:13:02 2009 +0000
@@ -20,6 +20,7 @@
 
 var components = executables.concat(libraries).concat(packages);
 var component_modules = {}
+var component_stats = {}
 var component_deps = {}
 
 
@@ -51,6 +52,7 @@
 {
 	for (i in components) {
 		component_modules[components[i]] = eval('modules_' + components[i].replaceAll('-', ''));
+		component_stats[components[i]] = eval('stats_' + components[i].replaceAll('-', ''));
 		component_deps[components[i]] = eval('deps_' + components[i].replaceAll('-', ''));
 	}
 }
@@ -459,7 +461,8 @@
 	html += '<table><tr><th>Module</th><th>Description</th></tr>\n';
 	modules = component_modules[component];
 	for (j in modules) {
-		html += '<tr><td><a href="?c=' + component + '&m=' + modules[j].name + '">' + modules[j].name + '</a></td>\n';
+		html += '<tr><td><a href="?c=' + component + '&m=' + modules[j].name + '">' + modules[j].name + '</a>';
+		html += ' <span class="stat">(' + Math.round(100 * (modules[j].compl_descr_cnt / modules[j].descr_cnt)) + '\%)</span></td>\n';
 		if (modules[j].description != "") {
 			d = modules[j].description;
 			if ((i = d.indexOf('.')) > -1)
@@ -470,6 +473,7 @@
 			html += '<td><span class="empty">to be completed!</span></td></tr>';
 	}
 	html += '</table>\n';
+	html += '<p class="stat">The percentages indicate how much of the source has been documented.</p>'
 	set_content(html);
 	
 	html = '<h2 class="title">Dependencies</h2>';
@@ -507,18 +511,35 @@
 	html = "";
 	html += '<table><tr>';
 	html += '<td width="30%"><h2>Executables</h2>';
+	total_descr_cnt = total_completed_descr_cnt = 0;
 	executables.sort()
-	for (i in executables)
-		html += '<a href="index.html?c=' + executables[i] + '">' + executables[i] + '</a><br />';
+	for (i in executables) {
+		stats = component_stats[executables[i]];
+		total_descr_cnt += stats.descr_cnt;
+		total_completed_descr_cnt += stats.completed_descr_cnt;
+		html += '<a href="index.html?c=' + executables[i] + '">' + executables[i] + '</a>';
+		html += ' <span class="stat">(' + 
+			Math.round(100 * stats.completed_descr_cnt / stats.descr_cnt) + '\%)</span><br />';
+	}
 	html += '</td><td width="30%"><h2>Libraries</h2>';
 	libraries.sort()
-	for (i in libraries)
-		html += '<a href="index.html?c=' + libraries[i] + '">' + libraries[i] + '</a><br />';
+	for (i in libraries) {
+		stats = component_stats[libraries[i]];
+		html += '<a href="index.html?c=' + libraries[i] + '">' + libraries[i] + '</a>';
+		html += ' <span class="stat">(' + 
+			Math.round(100 * stats.completed_descr_cnt / stats.descr_cnt) + '\%)</span><br />';
+	}
 	html += '</td><td width="30%"><h2>Packages</h2>';
 	packages.sort()
-	for (i in packages)
-		html += '<a href="index.html?c=' + packages[i] + '">' + packages[i] + '</a><br />';
+	for (i in packages) {
+		stats = component_stats[packages[i]];
+		html += '<a href="index.html?c=' + packages[i] + '">' + packages[i] + '</a>';
+		html += ' <span class="stat">(' + 
+			Math.round(100 * stats.completed_descr_cnt / stats.descr_cnt) + '\%)</span><br />';
+	}
 	html += '</td></tr></table>';
+	html += '<p class="stat">The percentages indicate how much of the source has been documented. Total ' +
+		Math.round(100 * total_completed_descr_cnt / total_descr_cnt) + '\% complete.</p>'
 	append_content(html);
 }
 
diff -r 2b994a4fda1e -r d6396c0904fc ocaml/doc/odoc_json.ml
--- a/ocaml/doc/odoc_json.ml	Fri Nov 20 16:13:02 2009 +0000
+++ b/ocaml/doc/odoc_json.ml	Fri Nov 20 16:13:02 2009 +0000
@@ -225,6 +225,14 @@
 class gen () =
 	object (self)
 	
+	(* Attributes *)
+	
+	val mutable g = []
+	val mutable descr_cnt = 0
+	val mutable completed_descr_cnt = 0
+	
+	(* Methods *)
+	
 	(* HTML *)
 	
 	method t_of_text = List.map self#t_of_text_element
@@ -402,26 +410,36 @@
 	method json_of_variant_constructor c =
 		let desc = match c.Type.vc_text with
 		| None -> []
-		| Some t -> ["description", String (print_t_list (self#t_of_text t))]
+		| Some t ->
+			completed_descr_cnt <- completed_descr_cnt + 1;
+			["description", String (print_t_list (self#t_of_text t))]
 		in
+		descr_cnt <- descr_cnt + 1;
 		Object (["name", String c.Type.vc_name] @ desc @ ["type", Array (List.map self#json_of_type_expr c.Type.vc_args)])
 
 	method json_of_record_field f =
 		let desc = match f.Type.rf_text with
 		| None -> []
-		| Some t -> ["description", String (print_t_list (self#t_of_text t))]
+		| Some t ->
+			completed_descr_cnt <- completed_descr_cnt + 1;
+			["description", String (print_t_list (self#t_of_text t))]
 		in
+		descr_cnt <- descr_cnt + 1;
 		Object (["name", String f.Type.rf_name; "mutable", json_of_bool f.Type.rf_mutable] @
 		desc @ ["type", self#json_of_type_expr f.Type.rf_type])
 	    
-	method json_of_info_opt = function
-	| None -> Empty
-    | Some i -> self#json_of_info i
+	method json_of_info_opt info =
+		descr_cnt <- descr_cnt + 1;
+		match info with
+		| None -> Empty
+		| Some i -> self#json_of_info i
     
 	method json_of_info i =
 		let desc = match i.i_desc with
 		| None -> []
-		| Some t -> ["description", String (print_t_list (self#t_of_text t))]
+		| Some t ->
+			completed_descr_cnt <- completed_descr_cnt + 1;
+			["description", String (print_t_list (self#t_of_text t))]
 		in
 		let authors = match List.map (fun s -> String s) i.i_authors with
 		| [] -> []
@@ -467,8 +485,6 @@
 	method json_of_raised_exception (s, t) =
 		Object ["raised_exception", String s; "text", String (print_t_list (self#t_of_text t))]
 
-	val mutable g = []
-
 	method json_of_module m =
 		let name = "name", String m.Module.m_name in
 		let loc = "location", self#json_of_loc m.Module.m_loc in
@@ -509,7 +525,7 @@
 		Object (name :: file :: loc :: info :: mte :: mk :: deps :: [])
 
 	method generate (modules_list : t_module list) =
-		let write_module_json (name, json) =
+		let write_module_json (name, json, _) =
 			let oc = open_out (!Odoc_args.target_dir ^ "/" ^ name ^ ".json") in
 			output_string oc ("odoc = " ^ (json_to_string 0 json));
 			close_out oc
@@ -517,13 +533,13 @@
 		let write_index_json ml =
 			let oc = open_out (!Odoc_args.target_dir ^ "/index.json") in
 			let make_record = function
-			| (name, Object ["module", Object m]) ->
+			| (name, Object ["module", Object m], (dc, cdc)) ->
 				let info = List.assoc "info" m in
 				let descr = match info with
 				| Object ["description", d] -> d
 				| _ -> Empty
 				in
-				Object ["name", String name; "description", descr]
+				Object ["name", String name; "description", descr; "descr_cnt", Number dc; "compl_descr_cnt", Number cdc]
 			| _ -> Empty
 			in
 			let modules = Array (List.map make_record ml) in
@@ -534,14 +550,20 @@
 				with _ -> !Odoc_args.target_dir
 			in
 			output_string oc ("modules_" ^ (replace "-" "" component) ^ " = " ^ (json_to_string 0 modules) ^ ";\n");
+			let stats = Object ["descr_cnt", Number (float_of_int descr_cnt); "completed_descr_cnt", Number (float_of_int completed_descr_cnt)] in
+			output_string oc ("stats_" ^ (replace "-" "" component) ^ " = " ^ (json_to_string 0 stats) ^ ";\n");
 			close_out oc
 		in
 		let create_module_json m =
-			m.Module.m_name, Object ["module", self#json_of_module m]
+			let cur_descr_cnt = descr_cnt in
+			let cur_completed_descr_cnt = completed_descr_cnt in
+			let json = self#json_of_module m in
+			m.Module.m_name, Object ["module", json],
+				(float_of_int (descr_cnt - cur_descr_cnt), float_of_int (completed_descr_cnt - cur_completed_descr_cnt))
 		in
 		let modules = List.map create_module_json modules_list in
 		let ig = invert_graph [] g in
-		let rec add_used_by (name, json) =
+		let rec add_used_by (name, json, stats) =
 			let used_by = Array (List.map (fun s -> String s) (List.assoc name ig)) in
 			let rec extend_object f tags = function
 			| Object l -> Object ((List.map (fun (s,o) -> s, extend_object f (tags @ [s]) o) l) @ f tags)
@@ -551,7 +573,7 @@
 			| ["module"; "dependencies"] -> ["used_by", used_by]
 			| l -> []
 			in
-			name, extend_object aux [] json
+			name, extend_object aux [] json, stats
 		in
 		let modules = List.map add_used_by modules in
 		List.iter write_module_json modules;
diff -r 2b994a4fda1e -r d6396c0904fc ocaml/doc/style.css
--- a/ocaml/doc/style.css	Fri Nov 20 16:13:02 2009 +0000
+++ b/ocaml/doc/style.css	Fri Nov 20 16:13:02 2009 +0000
@@ -73,6 +73,12 @@
 	width: 20em;
 	padding: 1em;
 	color: white;
+}
+
+
+#sidebar th {
+	text-align: left;
+	border-bottom: 1px solid white;
 }
 
 #footer {
@@ -241,3 +247,9 @@
 	text-align: right;
 }
 
+.stat {
+	font-size: 70%;
+	color: #cc3300;
+	vertical-align: top;
+}
+
diff -r 2b994a4fda1e -r d6396c0904fc ocaml/util/OMakefile
--- a/ocaml/util/OMakefile	Fri Nov 20 16:13:02 2009 +0000
+++ b/ocaml/util/OMakefile	Fri Nov 20 16:13:02 2009 +0000
@@ -3,7 +3,9 @@
 
 OCamlLibrary(sanitycheck, sanitycheck)
 OCamlLibrary(stats, stats)
+OCamlDocLibrary(stats, stats)
 OCamlLibrary(vm_memory_constraints, vm_memory_constraints)
+OCamlDocLibrary(vm_memory_constraints, vm_memory_constraints)
 OCamlLibrary(ocamltest, ocamltest)
 
 StaticCLibrary(backtrace_stub, backtrace_stub)