# HG changeset patch # User Rob Hoes [ocamldoc] Various minor tweaks Signed-off-by: Rob Hoes diff -r 904e7c4da5e0 .hgignore --- a/.hgignore Tue Oct 13 12:49:02 2009 +0100 +++ b/.hgignore Wed Jan 13 15:57:11 2010 +0000 @@ -114,6 +114,7 @@ ocaml/database/block_device_io ocaml/db_process/xapi-db-process ocaml/db_process/xapi-db-upgrade-4.2 +ocaml/doc/content ocaml/events/event_listen ocaml/fdhelper/closeandexec ocaml/fdhelper/closeandexec_static @@ -168,3 +169,5 @@ ocaml/xstest/xsbench ocaml/xstest/xstest ocaml/xstest/xscheckperms + +*/libs diff -r 904e7c4da5e0 ocaml/doc/example.mli --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/ocaml/doc/example.mli Wed Jan 13 15:57:11 2010 +0000 @@ -0,0 +1,55 @@ +(** A one-sentence description of the module. + * @group Module-group Heading + *) + +(** Some more explanation about the module, its implementation + * and purpose, and whatever else it useful to know. + *) + +(** {2 A Sub-heading Used to Group Various Functions} *) + +(** This is a description of the function [f], placed immediately above the function *) +val f : 'a -> 'b + +(** This is a description of the function [g], placed immediately above the function, + * while leaving at least one empty line after the previous function. *) +val g : int -> unit + +(** Besides functions, also other elements such as types and exceptions have comments. + * Note that also the values of a type are given descriptions of their own. *) +type t = +{ + a : string; (** [a] is a useful string *) + b : int; (** [b] is an awesome number *) +} + +(** A variant type *) +type q = +| Test of int * string (** Testing *) +| AnotherTest (** More testing *) + +(** {2 Another heading} *) + +(** + Additional comments, not associated to any element can be inserted anywhere. + This gives me the oppotunity to introduce some fancy formatting options, such as + - a bulleted list + - of items + + Or a numbered list: + + like + + this + + Text can be formatted as [source code], {i in italics}, {b in bold face}, and + links to a function such as {!Module.function} can be used. + + {3 Lower-level heading} + + Additional formatting options are listed in the OCamlDoc manual: + http://caml.inria.fr/pub/docs/manual-ocaml/manual029.html. +*) + +(** The order of all functions, comments, etc. in an mli file is maintained in + * the documentation. So this exception will appear at the end of the page. + *) +exception ThisWentTerriblyWrong of string diff -r 904e7c4da5e0 ocaml/doc/ocamldoc.js --- a/ocaml/doc/ocamldoc.js Tue Oct 13 12:49:02 2009 +0100 +++ b/ocaml/doc/ocamldoc.js Wed Jan 13 15:57:11 2010 +0000 @@ -36,24 +36,13 @@ else return qs[1]; } - -// function from http://www.codedigest.com/CodeDigest/75-String-ReplaceAll-function-in-JavaScript.aspx -String.prototype.replaceAll = function(stringToFind,stringToReplace){ - var temp = this; - var index = temp.indexOf(stringToFind); - while(index != -1){ - temp = temp.replace(stringToFind,stringToReplace); - index = temp.indexOf(stringToFind); - } - return temp; - } function fill_components() { 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('-', '')); + component_modules[components[i]] = eval('modules_' + components[i].replace(/\-/g, '')); + component_stats[components[i]] = eval('stats_' + components[i].replace(/\-/g, '')); + component_deps[components[i]] = eval('deps_' + components[i].replace(/\-/g, '')); } } @@ -118,53 +107,45 @@ return "2" } +function construct_url(mod, fn) +{ + comp = find_component_for_module(mod.split('.')[0]); + if (comp != "") + return 'index.html?c=' + comp + '&m=' + mod + '#' + fn; + else + return '#'; +} + function transform_links(s) { - out = ""; - a = 0; - b = s.indexOf('{'); - while (b >= 0) { - out += s.substr(a, b-a); - a = b + 1; - b = s.indexOf('}', a); - link = s.substr(a, b-a); - - f = link.split('|')[1]; - m = f.lastIndexOf('.'); - c = find_component_for_module(f.substr(0, m)); - if (c != "") - out += 'index.html?c=' + c + '&m=' + f.substr(0, m) + '#' + f.substr(m+1); - else - out += '#'; - - a = b + 1; - b = s.indexOf('{', a); - } - out += s.substr(a); - return out; + return s.replace(/\{\w*\|([\w|\.]*)\.(\w*)\}/g, function(x,y,z){return construct_url(y, z)}); } function transform_type(t) { - if (t != '') { + if (t != undefined && t != '') { params = t.split('->'); for (i in params) { u = params[i]; - if (u[0] == '?') - optional = ' (optional)'; + if (u.indexOf('?') > -1) + optional = 'optional '; else optional = ''; - a = u.indexOf(':'); - if (a > -1) - u = u.substr(a + 1); - params[i] = '' + u + optional + ''; + u = u.replace(/[^\(]*:/, ''); + params[i] = optional + u; } - html = params.join('\u2192'); - // the following is obviously a bit inefficient... - for (i = 0; i < 25; i++) - html = html.replaceAll("'" + String.fromCharCode(0x61 + i), - String.fromCharCode(0x3b1 + i)); - html = html.replaceAll('*', '\u00d7'); + // put back arrows + html = params.join(' \u2192 '); + // remove Pervasives. + html = html.replace(/Pervasives\./g, ''); + // replace polymorphic params by greek letters + html = html.replace(/\'([a-z])/g, function(x,y){return String.fromCharCode(y.charCodeAt(0) + 0x3b1 - 0x61)}); + // replaces asteriskes by times symbols + html = html.replace(/\*/g, '\u00d7'); + // replace brackets + html = html.replace(/(\(|\))/g, '$1'); + // add links to known types + html = html.replace(/([A-Z][\w|\.]*)\.(\w*)/g, function(x,y,z){return '' + y + '.' + z + ''}); } else html = '[none]'; @@ -177,8 +158,30 @@ name = l[l.length - 1]; html = '
'; + if (v.params.length > 0) + html += ''; html += '
[value]
'; html += '
' + name + '
'; + + html += ''; + html += '';*/ + html += ''; + + html += ''; + html += '
Type:' + transform_type(v.type); +/* if (v.params.length > 0) + html += '
'; + if (v.info.deprecated != undefined) { html += '
Deprecated ' + v.info.deprecated + '
'; } @@ -189,24 +192,6 @@ else html += 'to be completed!
'; - html += ''; - html += ''; - - html += ''; - - if (v.params.length > 0) - html += ''; - - html += '
Type:' + transform_type(v.type) + '
'; - html += ''; append_content(html); } @@ -219,18 +204,18 @@ html = '
'; html += '
[exception]
'; html += '
' + name + '
'; + html += ''; + html += ''; + else + html += '[none]'; + html += '
Arguments:'; + if (v.exception_args != undefined) + html += transform_type(v.exception_args.join(' * ')) + '
'; html += '
'; if (v.info.description != undefined) html += transform_links(v.info.description) + '
'; else html += 'to be completed!
'; - html += ''; - html += ''; - else - html += '[none]'; - html += '
Arguments:'; - if (v.exception_args != undefined) - html += v.exception_args + '
'; html += ''; append_content(html); } @@ -243,7 +228,7 @@ html += 'ConstructorTypeDescription'; for (c in cons) { html += '' + cons[c].name + '' - html += '' + transform_type(cons[c].type) + '' + html += '' + transform_type(cons[c].type.join(' * ')) + '' if (cons[c].description != undefined) html += '' + transform_links(cons[c].description) + ''; else @@ -278,7 +263,7 @@ name = l[l.length - 1]; html = '
'; - html += '
[type]
'; + html += '
[' + v.kind.type + ' type]
'; html += '
' + name + '
'; html += '
'; if (v.info.description != undefined) @@ -289,8 +274,6 @@ html += variant(v.kind); else if (v.kind.type == 'record') html += record(v.kind); - else if (v.kind.type == 'abstract') - html += 'abstract type' html += '
'; append_content(html); } @@ -324,6 +307,7 @@ name = l[l.length - 1]; html = '
'; + html += ''; html += '
[module]
'; html += '
' + name + '
'; html += '
'; @@ -333,8 +317,6 @@ html += 'to be completed!
'; html += ''; html += ''; - - html += ''; html += '
Type:' + transform_type(v.type) + '
'; html += '
'; append_content(html); @@ -477,8 +459,11 @@ else html += 'to be completed!
'; set_content(html); - - parse_structure(mod.module_structure); + + if (mod.module_structure != undefined) + parse_structure(mod.module_structure); + else if (mod.module_functor != undefined) + parse_structure(mod.module_functor.module_structure); } function module_index() diff -r 904e7c4da5e0 ocaml/doc/odoc_json.ml --- a/ocaml/doc/odoc_json.ml Tue Oct 13 12:49:02 2009 +0100 +++ b/ocaml/doc/odoc_json.ml Wed Jan 13 15:57:11 2010 +0000 @@ -494,36 +494,41 @@ method json_of_raised_exception (s, t) = Object ["raised_exception", String s; "text", html_to_json (self#t_of_text t)] + method json_of_module_parameter mparam = + let name = "name", String mparam.Module.mp_name in + Object (name :: []) + + method json_of_module_kind = function + | Module_struct l -> + "module_structure", Array (List.map self#json_of_module_element l) + | Module_alias ma -> + "module_alias", String "unavailable" (* self#t_of_module_alias ma *) + | Module_functor (mparam, mk) -> + "module_functor", Object (["parameter", self#json_of_module_parameter mparam; self#json_of_module_kind mk]) +(* node "module_functor" + [ self#t_of_module_parameter mparam ; self#t_of_module_kind mk]*) + | Module_apply (mk1, mk2) -> + "module_apply", String "unavailable" +(* node "module_apply" + [ self#t_of_module_kind mk1 ; self#t_of_module_kind mk2]*) + | Module_with (mk, s) -> + "module_with", String "unavailable" +(* node "module_with" + [ self#t_of_module_type_kind mk; node "with" [Leaf s] ]*) + | Module_constraint (mk, mtk) -> + self#json_of_module_kind mk +(* node "module_constraint" + [ self#t_of_module_kind mk ; + self#t_of_module_type_kind mtk ; + ]*) + 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 let deps = "dependencies", Object ["uses", Array (List.map (fun d -> String d) m.Module.m_top_deps)] in let file = "file", String m.Module.m_file in let mte = "type", String (Odoc_info.string_of_module_type m.Module.m_type) in - let mk = match m.Module.m_kind with - | Module_struct l -> - "module_structure", Array (List.map self#json_of_module_element l) - | Module_alias ma -> - "module_alias", String "unavailable" (* self#t_of_module_alias ma *) - | Module_functor (mparam, mk) -> - "module_functor", String "unavailable" -(* node "module_functor" - [ self#t_of_module_parameter mparam ; self#t_of_module_kind mk]*) - | Module_apply (mk1, mk2) -> - "module_apply", String "unavailable" -(* node "module_apply" - [ self#t_of_module_kind mk1 ; self#t_of_module_kind mk2]*) - | Module_with (mk, s) -> - "module_with", String "unavailable" -(* node "module_with" - [ self#t_of_module_type_kind mk; node "with" [Leaf s] ]*) - | Module_constraint (mk, mtk) -> - "module_constraint", String "unavailable" -(* node "module_constraint" - [ self#t_of_module_kind mk ; - self#t_of_module_type_kind mtk ; - ]*) - in + let mk = self#json_of_module_kind m.Module.m_kind in let info = "info", self#json_of_info_opt m.Module.m_info in (* dependencies *) diff -r 904e7c4da5e0 ocaml/doc/style.css --- a/ocaml/doc/style.css Tue Oct 13 12:49:02 2009 +0100 +++ b/ocaml/doc/style.css Wed Jan 13 15:57:11 2010 +0000 @@ -16,9 +16,10 @@ padding: 0; margin: 0; border: 0; - font: 80% helvetica, arial, sans-serif; + font-family: "Nimbus Sans L", "Trebuchet MS", Helvetica, Arial, sans-serif; + font-size: 80%; font-weight: normal; - line-height: 130%; + line-height: 140%; background: white; color : black; background-color: #eee; @@ -31,7 +32,7 @@ #header { width: 100%; - height: 55px; + height: 4.5em; margin: 0; padding: 0; color: white; @@ -66,7 +67,7 @@ background-color: #ffffdd; padding: 1.5em 1em; margin: 0 22em 0 .5em; - line-height: 150%; + line-height: 170%; } #sidebar { @@ -204,7 +205,7 @@ } tt, .code { - font: 1.2em monospace; + font: 1.3em monospace; font-weight: inherit; } @@ -245,12 +246,14 @@ } .field-table td { - padding: .3em 0; + padding: .3em .5em .3em 0; } .small-button { font-size: 70%; - text-align: right; +// text-align: right; + float: right; + margin: .5em 0; } .stat { @@ -262,13 +265,21 @@ .type { } -.arrow { - font-size: 150%; +.symbol { + font-family: sans-serif; color: #cc6600; - padding: 0 3px; +} + +.large { + font-size: 130%; +} + +.spaced { + padding: 0 0.3em; } .optional { font-size: 70%; vertical-align: top; } + diff -r 904e7c4da5e0 ocaml/xiu/OMakefile --- a/ocaml/xiu/OMakefile Tue Oct 13 12:49:02 2009 +0100 +++ b/ocaml/xiu/OMakefile Wed Jan 13 15:57:11 2010 +0000 @@ -2,6 +2,7 @@ OCAML_LIBS += ../xenops/xenops ../netdev/netdev OCAMLINCLUDES += ../xenops ../netdev OCamlProgram(xiu, xiu) +OCamlDocProgram(xiu, xiu) .PHONY: clean clean: