# 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 +
xen-api.hg-3.patch
Description: Text Data
_______________________________________________
xen-api mailing list
xen-api@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/mailman/listinfo/xen-api
|
Home