|
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [Xen-API] [PATCH] [ocamldoc] Various minor tweaks
# HG changeset patch
# User Rob Hoes <rob.hoes@xxxxxxxxxx>
[ocamldoc] Various minor tweaks
Signed-off-by: Rob Hoes <rob.hoes@xxxxxxxxxx>
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 = ' <span
class="optional">(optional)</span>';
+ if (u.indexOf('?') > -1)
+ optional = '<span
class="optional">optional</span> ';
else
optional = '';
- a = u.indexOf(':');
- if (a > -1)
- u = u.substr(a + 1);
- params[i] = '<span class="type">' + u + optional +
'</span>';
+ u = u.replace(/[^\(]*:/, '');
+ params[i] = optional + u;
}
- html = params.join('<span class="arrow">\u2192</span>');
- // 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(' <span class="symbol large
spaced">\u2192</span> ');
+ // 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, '<span
class="symbol">\u00d7</span>');
+ // replace brackets
+ html = html.replace(/(\(|\))/g, '<span class="symbol
large">$1</span>');
+ // add links to known types
+ html = html.replace(/([A-Z][\w|\.]*)\.(\w*)/g,
function(x,y,z){return '<a href="' + construct_url(y, z) + '">' + y + '.' + z +
'</a>'});
}
else
html = '[none]';
@@ -177,8 +158,30 @@
name = l[l.length - 1];
html = '<div class="field' + toggle(n) + '">';
+ if (v.params.length > 0)
+ html += '<input type="button" class="small-button" value="show
parameters" onclick="document.getElementById(\'' + name +
'_params\').style.display=\'\';" />';
html += '<div class="field-type"><a name="' + name +
'">[value]</a></div>';
html += '<div class="field-name">' + name + '</div>';
+
+ html += '<table class="field-table">';
+ html += '<tr><td width="100px"><span
class="field-head">Type:</span></td><td>' + transform_type(v.type);
+/* if (v.params.length > 0)
+ html += '<tr><td></td><td><input type="button"
class="small-button" value="parameters" onclick="document.getElementById(\'' +
name + '_params\').style.display=\'\';
this.parentNode.parentNode.style.display=\'none\'" /></td></tr>';*/
+ html += '</td></tr>';
+
+ html += '<tr id="' + name +
+ '_params" style="display: none"><td width="100px"><span
class="field-head">Parameters:</span></td><td>';
+ html += '<table>';
+ for (c in v.params) {
+ n = v.params[c].name;
+ html += '<tr><td width="20%" style="padding: 0 0 .2em">' +
+ (n == "" ? '(no name)' : v.params[c].name) + '</td>';
+ html += '<td style="padding: 0 0 .2em">' +
transform_type(v.params[c].type) + '</td></tr>';
+ }
+ html += '</table>';
+ html += '</td></tr>';
+ html += '</table>';
+
if (v.info.deprecated != undefined) {
html += '<div class="deprecated"><b>Deprecated</b> ' +
v.info.deprecated + '</div>';
}
@@ -189,24 +192,6 @@
else
html += '<span class="empty">to be completed!</span></div>';
- html += '<table class="field-table">';
- html += '<tr><td width="100px"><span
class="field-head">Type:</span></td><td>' + transform_type(v.type) +
'</td></tr>';
-
- html += '<tr id="' + name + '_params" style="display: none"><td
width="100px"><span class="field-head">Parameters:</span></td><td>';
- html += '<table>';
- for (c in v.params) {
- n = v.params[c].name;
- html += '<tr><td width="20%" style="padding: 0 0 .2em">' + (n
== "" ? '(no name)' : v.params[c].name) + '</td>';
- html += '<td style="padding: 0 0 .2em">' +
transform_type(v.params[c].type) + '</td></tr>';
- }
- html += '</table>';
- html += '</td></tr>';
-
- if (v.params.length > 0)
- html += '<tr><td></td><td><input type="button"
class="small-button" value="parameters" onclick="document.getElementById(\'' +
name + '_params\').style.display=\'\'; this.style.display=\'none\'"
/></td></tr>';
-
- html += '</table>';
-
html += '</div>';
append_content(html);
}
@@ -219,18 +204,18 @@
html = '<div class="field' + toggle(n) + '">';
html += '<div class="field-type"><a name="' + name +
'">[exception]</a></div>';
html += '<div class="field-name">' + name + '</div>';
+ html += '<table class="field-table">';
+ html += '<tr><td width="100px"><span
class="field-head">Arguments:</span></td><td>';
+ if (v.exception_args != undefined)
+ html += transform_type(v.exception_args.join(' * ')) +
'</td></tr>';
+ else
+ html += '[none]</td></tr>';
+ html += '</table>';
html += '<div class="field-description">';
if (v.info.description != undefined)
html += transform_links(v.info.description) + '</div>';
else
html += '<span class="empty">to be completed!</span></div>';
- html += '<table class="field-table">';
- html += '<tr><td width="100px"><span
class="field-head">Arguments:</span></td><td>';
- if (v.exception_args != undefined)
- html += v.exception_args + '</td></tr>';
- else
- html += '[none]</td></tr>';
- html += '</table>';
html += '</div>';
append_content(html);
}
@@ -243,7 +228,7 @@
html += '<tr><th
width="25%">Constructor</th><th>Type</th><th>Description</th></tr>';
for (c in cons) {
html += '<tr><td>' + cons[c].name + '</td>'
- html += '<td>' + transform_type(cons[c].type) + '</td>'
+ html += '<td>' + transform_type(cons[c].type.join(' * ')) +
'</td>'
if (cons[c].description != undefined)
html += '<td>' + transform_links(cons[c].description) +
'</td>';
else
@@ -278,7 +263,7 @@
name = l[l.length - 1];
html = '<div class="field' + toggle(n) + '">';
- html += '<div class="field-type"><a name="' + name +
'">[type]</a></div>';
+ html += '<div class="field-type"><a name="' + name + '">[' +
v.kind.type + ' type]</a></div>';
html += '<div class="field-name">' + name + '</div>';
html += '<div class="field-description">';
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 += '</div>';
append_content(html);
}
@@ -324,6 +307,7 @@
name = l[l.length - 1];
html = '<div class="field' + toggle(n) + '">';
+ html += '<input type="button" class="small-button" value="show details"
onclick="location=\'index.html?c=' + component + '&m=' + v.name + '\'" />';
html += '<div class="field-type"><a name="' + name +
'">[module]</a></div>';
html += '<div class="field-name">' + name + '</div>';
html += '<div class="field-description">';
@@ -333,8 +317,6 @@
html += '<span class="empty">to be completed!</span></div>';
html += '<table class="field-table">';
html += '<tr><td width="100px"><span
class="field-head">Type:</span></td><td>' + transform_type(v.type) +
'</td></tr>';
-
- html += '<tr><td></td><td><input type="button" class="small-button"
value="details" onclick="location=\'index.html?c=' + component + '&m=' + v.name
+ '\'" /></td></tr>';
html += '</table>';
html += '</div>';
append_content(html);
@@ -477,8 +459,11 @@
else
html += '<span class="empty">to be completed!</span></div>';
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:
Attachment:
doc-misc _______________________________________________ xen-api mailing list xen-api@xxxxxxxxxxxxxxxxxxx http://lists.xensource.com/mailman/listinfo/xen-api
|
 |
Lists.xenproject.org is hosted with RackSpace, monitoring our |