[Xen-API] [PATCH 2 of 3] [ocamldoc] Information on the completeness of the documentation

[Rob Hoes <rob.hoes@xxxxxxxxxx>]

# 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)
4 files changed, 78 insertions(+), 21 deletions(-)
ocaml/doc/ocamldoc.js  |   35 ++++++++++++++++++++++++++-------
ocaml/doc/odoc_json.ml |   50 ++++++++++++++++++++++++++++++++++--------------
ocaml/doc/style.css    |   12 +++++++++++
ocaml/util/OMakefile   |    2 +

Attachment: xen-api.hg-3.patch
Description: Text Data

_______________________________________________
xen-api mailing list
xen-api@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/mailman/listinfo/xen-api