Corrections as per code review.

Signed-off-by: Konstantina Chremmou <[email protected]>

ocaml/doc/basics.md

@@ -5,12 +5,12 @@
 # API Basics
 
 This document defines the XenServer Management API - an interface for remotely
-configuring and controlling virtualised guests running on a Xen-enabled host.
+configuring and controlling virtualized guests running on a Xen-enabled host.
 
 The API is presented here as a set of Remote Procedure Calls (RPCs). There are
 two supported wire formats, one based upon [XML-RPC](http://xmlrpc.scripting.com/spec.html)
 and one based upon [JSON-RPC](http://www.jsonrpc.org) (v1.0 and v2.0 are both
-recognised). No specific language bindings are prescribed, although examples
+recognized). No specific language bindings are prescribed, although examples
 will be given in the python programming language.
 
 Although we adopt some terminology from object-oriented programming,

ocaml/doc/wire-protocol.md

@@ -182,7 +182,7 @@ following manner:
 
 * our `void` type is transmitted as an empty string.
 
-Both versions 1.0 and 2.0 of the JSON-RPC wire format are recognised and,
+Both versions 1.0 and 2.0 of the JSON-RPC wire format are recognized and,
 depending on your client library, you can use either of them.
 
 ### JSON-RPC v1.0
@@ -490,7 +490,7 @@ session reference is returned under the key `Value` in the resulting dictionary
 ...                                           "version", "originator")['Value']
 ```
 
-This is what the call looks like when serialised
+This is what the call looks like when serialized
 
 ```xml
 <?xml version='1.0'?>
@@ -534,7 +534,7 @@ Once a reference to a VM has been acquired, a lifecycle operation may be invoked
 In this case the `start` message has been rejected, because the VM is
 a template, and so an error response has been returned.  These high-level
 errors are returned as structured data (rather than as XML-RPC faults),
-allowing them to be internationalised.
+allowing them to be internationalized.
 
 Rather than querying fields individually, whole _records_ may be returned at once.
 To retrieve the record of a single object as a python dictionary:
@@ -579,7 +579,7 @@ reference:
 ...                       "user", "passwd", "version", "originator")
 ```
 
-`pyjsonrpc` uses the JSON-RPC protocol v2.0, so this is what the serialised
+`pyjsonrpc` uses the JSON-RPC protocol v2.0, so this is what the serialized
 request looks like:
 
 ```json
@@ -627,7 +627,7 @@ Once a reference to a VM has been acquired, a lifecycle operation may be invoked
 
 In this case the `start` message has been rejected because the VM is
 a template, hence an error response has been returned. These high-level
-errors are returned as structured data, allowing them to be internationalised.
+errors are returned as structured data, allowing them to be internationalized.
 
 Rather than querying fields individually, whole _records_ may be returned at once.
 To retrieve the record of a single object as a python dictionary:

ocaml/idl/datamodel.ml

@@ -2057,7 +2057,10 @@ module Bond = struct
   let t =
     create_obj ~in_db:true ~in_product_since:rel_miami ~in_oss_since:None
       ~persist:PersistEverything ~gen_constructor_destructor:false ~name:_bond
-      ~descr:"" ~gen_events:true ~doccomments:[]
+      ~descr:
+        "A Network bond that combines physical network interfaces, also known \
+         as link aggregation"
+      ~gen_events:true ~doccomments:[]
       ~messages_default_allowed_roles:_R_POOL_OP ~doc_tags:[Networking]
       ~messages:[create; destroy; set_mode; set_property]
       ~contents:

ocaml/idl/datamodel_certificate.ml

@@ -34,7 +34,8 @@ let certificate_type =
     )
 
 let t =
-  create_obj ~name:_certificate ~descr:"Description" ~doccomments:[]
+  create_obj ~name:_certificate
+    ~descr:"An X509 certificate used for TLS connections" ~doccomments:[]
     ~gen_constructor_destructor:false ~gen_events:true ~in_db:true ~lifecycle
     ~persist:PersistEverything ~in_oss_since:None
     ~messages_default_allowed_roles:_R_READ_ONLY

ocaml/idl/markdown_backend.ml

@@ -185,7 +185,10 @@ let generate_class cls =
                        ( "field_name"
                        , `String
                            (pad_right
-                              (escape (Datamodel_utils.wire_name_of_field field))
+                              ("`"
+                              ^ Datamodel_utils.wire_name_of_field field
+                              ^ "`"
+                              )
                               col_width_20
                            )
                        )
@@ -298,7 +301,8 @@ let generate_class cls =
                                     [
                                       ( "param_name"
                                       , `String
-                                          (pad_right (escape p.param_name)
+                                          (pad_right
+                                             ("`" ^ p.param_name ^ "`")
                                              col_width_30
                                           )
                                       )
@@ -357,7 +361,7 @@ let generate_types system =
                  | Enum (name, options) ->
                      `O
                        [
-                         ("enum", `String (pad_right name (col_width_40 - 5)))
+                         ("enum", `String name)
                        ; ( "enum_options"
                          , `A
                              (options

ocaml/idl/templates/api_errors.mustache

@@ -9,15 +9,19 @@ or RPC level, the server may send an HTTP 500 error response, or the client
 may simulate the same. The client must be prepared to handle these errors,
 though they may be treated as fatal.
 
-On the wire, these are transmitted in a form similar to this when using the
-XML-RPC protocol:
+For example, the following malformed request when using the XML-RPC protocol:
 
-```
+```sh
 $curl -D - -X POST https://server -H 'Content-Type: application/xml' \
 > -d '<?xml version="1.0"?>
 > <methodCall>
 >   <methodName>session.logout</methodName>
 > </methodCall>'
+```
+
+results to the following response:
+
+```sh
 HTTP/1.1 500 Internal Error
 content-length: 297
 content-type:text/html
@@ -32,13 +36,18 @@ t;close_tag&quot;, &quot;open_tag&quot;, _)</body></html>
 
 When using the JSON-RPC protocol:
 
-```
+```sh
 $curl -D - -X POST https://server/jsonrpc -H 'Content-Type: application/json' \
 > -d '{
 >     "jsonrpc": "2.0",
 >     "method": "session.login_with_password",
 >     "id": 0
 > }'
+```
+
+the response is:
+
+```sh
 HTTP/1.1 500 Internal Error
 content-length: 308
 content-type:text/html
@@ -52,7 +61,7 @@ d_request(&quot;{jsonrpc=...,method=...,id=...}&quot;)</body></html>
 ```
 
 All other failures are reported with a more structured error response, to
-allow better automatic response to failures, proper internationalisation of
+allow better automatic response to failures, proper internationalization of
 any error message, and easier debugging.
 
 On the wire, these are transmitted like this when using the XML-RPC protocol:

ocaml/idl/templates/class.mustache

@@ -60,10 +60,10 @@ _Signature:_
 
 _Arguments:_
 
-|type                          |name                          |description                             |
+|Type                          |Name                          |Description                             |
 |:-----------------------------|:-----------------------------|:---------------------------------------|
 {{#session}}
-|session ref                   |session_ref                   |Reference to a valid session            |
+|`session ref`                 |`session_ref`                 |Reference to a valid session            |
 {{/session}}
 {{#rpc_params}}
 |{{{param_type}}}|{{{param_name}}}|{{{param_descr}}}|

ocaml/idl/templates/relationships.mustache

@@ -6,14 +6,13 @@
 
 Fields that are bound together are shown in the following table:
 
-|_object.field_                          |_object.field_                          |_relationship_ |
-|:---------------------------------------|:---------------------------------------|:--------------|
+|_object.field_                        |_object.field_                        |_relationship_ |
+|:-------------------------------------|:-------------------------------------|:--------------|
 {{#relationships}}
 |{{{a_field}}}|{{{b_field}}}|{{relationship}}|
 {{/relationships}}
 
-The following figure represents bound fields (as specified above)
-diagramatically, using crow's foot notation to specify one-to-one,
-one-to-many, or many-to-many relationships:
+The following figure represents bound fields (as specified above) using crow's
+foot notation to specify one-to-one, one-to-many, or many-to-many relationships:
 
 ![Class relationships](classes.png 'Class relationships')

ocaml/idl/templates/types.mustache

@@ -9,31 +9,33 @@
 The following primitive types are used to specify methods and fields in
 the API Reference:
 
-|Type    |Description                                 |
-|:-------|:-------------------------------------------|
-|string  |text strings                                |
-|int     |64-bit integers                             |
-|float   |IEEE double-precision floating-point numbers|
-|bool    |boolean                                     |
-|datetime|date and timestamp                          |
+|Type      |Description                                 |
+|:---------|:-------------------------------------------|
+|`string`  |text strings                                |
+|`int`     |64-bit integers                             |
+|`float`   |IEEE double-precision floating-point numbers|
+|`bool`    |boolean                                     |
+|`datetime`|date and timestamp                          |
 
 ## Higher-order types
 
 The following type constructors are used:
 
-|Type              |Description                                             |
-|:-----------------|:-------------------------------------------------------|
-|_c_ ref           |reference to an object of class _c_                     |
-|_t_ set           |a set of elements of type _t_                           |
-|(_a -> b_) map     |a table mapping values of type _a_ to values of type _b_|
+|Type          |Description                                             |
+|:-------------|:-------------------------------------------------------|
+|`c ref`       |reference to an object of class `c`                     |
+|`t set`       |a set of elements of type `t`                           |
+|`(a -> b) map`|a table mapping values of type `a` to values of type `b`|
 
 ## Enumeration types
 
 The following enumeration types are used:
 {{#enums}}
 
-|enum {{{enum}}}|                                        |
-|:---------------------------------------|:---------------------------------------|
+### Enum {{{enum}}}
+
+|Named value                             |Description                                          |
+|:---------------------------------------|:----------------------------------------------------|
 {{#enum_options}}
 |{{{option_name}}}|{{{option_descr}}}|
 {{/enum_options}}