[Docs] Continue to improve the Mono runtime documentation

8 files changed, 126 insertions, 68 deletions

diff --git a/docs/api-style.css b/docs/api-style.css
index 001df1b4c73..1f6483919cf 100644
--- a/docs/api-style.css
+++ b/docs/api-style.css
@@ -3,12 +3,22 @@
 	padding-left: 2em;
 	padding-right: 2em;
     }
+    .mapi-docs p {
+	max-width: 60em;
+    }
+    .mapi-docs .mapi-body {
+	max-width: 60em;
+    }
+    .mapi-docs code {
+        border: 1px solid rgba(214,214,214,1);
+	background-color: rgba(249,249,249,1);
+	padding: 0.1em 0.5em;
+    }
     .mapi-description code {
         font-family: "Consolas", "Courier", monospace;
         border: 1px solid rgba(214,214,214,1);
 	background-color: rgba(249,249,249,1);
-	padding-left: 3px;
-	padding-right: 3px;
+	padding: 0.1em 0.2em;
     }
 
     .mapi-header {
@@ -17,6 +27,20 @@
         white-space: pre;
         font-family: monospace;
         border: 1px solid rgba(233,233,233,1);
+	background-color: rgba(249,249,249,1);
+    }
+
+    .mapi-code {
+        padding: 5pt 5pt;
+        margin: 10pt;
+        white-space: pre;
+        font-family: monospace;
+        border: 1px solid rgba(233,233,233,1);
+	background-color: rgba(249,249,249,1);
+    }
+
+    .mapi-code:first-line {
+        line-height: 0px;
     }
 
     .mapi-entry code {
diff --git a/docs/exdoc b/docs/exdoc
index 058a2f7b962..e77e6d122a7 100644
--- a/docs/exdoc
+++ b/docs/exdoc
@@ -178,7 +178,6 @@ sub process_doc {
 	$body = "";
 	$functions[$fn++] = $func;
 	$deprecated = 0;
-	
 	# Process arguments
 	while (<>){
 	    s/NULL/<code>NULL<\/code>/g;
@@ -217,7 +216,7 @@ sub process_doc {
 		}
 		chop;
 		s/^\ \*//;
-		$_ = "\n<p>" if (/^\s+$/);
+		$_ = "<p>" if (/^\s*$/);
 				
 		if ($inbody == 0){
 		    if (/\s*(\w+):(.*)/){
@@ -230,6 +229,7 @@ sub process_doc {
 		    } else {
 			
 			$body = "\t$_\n";
+
 			$inbody = 1;
 		    }
 		} elsif ($inbody == 1) {
diff --git a/docs/sources/mono-api-exc.html b/docs/sources/mono-api-exc.html
index f6504355ebc..88c22a1f3e8 100644
--- a/docs/sources/mono-api-exc.html
+++ b/docs/sources/mono-api-exc.html
@@ -1,25 +1,32 @@
 <h2>Exception Handling</h2>
 
-<div class="mapi-header">
-@API_IDX@
-</div>
+	<p>Mono's exception handling contains methods
+	to <a href="#creating">create `MonoException*` objects</a>
+	that can be <a href="api:mono_raise_exception">raised</a>.
 
+	<p>Alternatively, you can obtain an exception that you can
+	raise from some of the most <a href="#common">common</a>
+	exceptions in the .NET Runtime.
+	
 <h3>Raising and Catching exceptions</h3>
 
-	<p>With the introduction of the Cooperative mode/Bitcode for
-	the Mono garbage collector, it is no longer recommended for
-	embedded developers to raise exceptions from any method except
-	the topmost registered internal call.
+	<p>If you plan on running your code in Mono's Cooperative mode
+	for the Garbage Collector (for example, if you are using pure
+	Bitcode code generation), it you should avoid raising an
+	exception from any method that is not the entry point to the
+	internal call. 
+
+	<p>It is recommended that if you need to raise an error
+	condition from nested parts of your code, surface this error
+	to the topmost method that is surfaced as an internal call and
+	raise the exception there.
 
-	<p>It is recommended that you raise an error condition from
-	nested parts of code, surface this error and in the topmost
-	frame raise the exception.
 	
 <h4><a name="api:mono_raise_exception">mono_raise_exception</a></h4>
 <h4><a name="api:mono_unhandled_exception">mono_unhandled_exception</a></h4>
 <h4><a name="api:mono_print_unhandled_exception">mono_print_unhandled_exception</a></h4>
 
-
+<a name="creating"/>
 <h3>Exception Types: General API</h3>
 
 <h4><a name="api:mono_exception_from_name_domain">mono_exception_from_name_domain</a></h4>
@@ -27,6 +34,7 @@
 <h4><a name="api:mono_exception_from_name_msg">mono_exception_from_name_msg</a></h4>
 <h4><a name="api:mono_exception_from_name_two_strings">mono_exception_from_name_two_strings</a></h4>
 
+<a name="common"/>
 <h3>Obtaining Common Exceptions</h3>
 
 	<p>There are a number of common exceptions that are used by
diff --git a/docs/sources/mono-api-gchandle.html b/docs/sources/mono-api-gchandle.html
index ccd468823fb..3ff8536dd39 100644
--- a/docs/sources/mono-api-gchandle.html
+++ b/docs/sources/mono-api-gchandle.html
@@ -31,7 +31,8 @@
 	<tt>mono_gchandle_get_target</tt>.
 
 	<p>For example, consider the following C code:
-<div class="code">
+
+<div class="mapi-code">
 static MonoObject* o = NULL;
 </div>
 
@@ -41,22 +42,22 @@ static MonoObject* o = NULL;
 	it from being collected, you need to acquire a GC handle for
 	it.
 
-<div class="code">
-        guint32 handle = mono_gchandle_new (my_object, TRUE);
+<div class="mapi-code">
+guint32 handle = mono_gchandle_new (my_object, TRUE);
 </div>
 
 	<p>TRUE means the object will be pinned, so it won't move in
 	memory when we'll use a moving GC. You can access the
 	MonoObject* referenced by a handle with:
 
-<div class="code">
-        MonoObject* obj = mono_gchandle_get_target (handle);
+<div class="mapi-code">
+MonoObject* obj = mono_gchandle_get_target (handle);
 </div>
 
 	<p>When you don't need the handle anymore you need to call:
 
-<div class="code">
-        mono_gchandle_free (handle);
+<div class="mapi-code">
+mono_gchandle_free (handle);
 </div>
 
 	<p>Note that if you assign a new object to the C var, you need
@@ -65,27 +66,27 @@ static MonoObject* o = NULL;
 
 	<p>So code that looked like this:
 
-<div class="code">
-        static MonoObject* o = NULL;
-        ...
-        o = mono_object_new (...);
-        /* use o */
-        ...
-        /* when done to allow the GC to collect o */
-        o = NULL;
+<div class="mapi-code">
+static MonoObject* obj = NULL;
+...
+obj = mono_object_new (...);
+// use obj
+...
+// when done to allow the GC to collect obj
+obj = NULL;
 </div>
 
 	<p>should now be changed to:
 
-<div class="code">
-        static guint32 o_handle;
-        ...
-        MonoObject *o = mono_object_new (...);
-        o_handle = mono_gchandle_new (o, TRUE);
-        /* use o or mono_gchandle_get_target (o_handle) */
-        ...
-        /* when done to allow the GC to collect o */
-        mono_gchandle_free (o_handle);
+<div class="mapi-code">
+static guint32 o_handle;
+...
+MonoObject *obj = mono_object_new (...);
+o_handle = mono_gchandle_new (obj, TRUE);
+// use o or mono_gchandle_get_target (o_handle) 
+...
+// when done to allow the GC to collect obj
+mono_gchandle_free (o_handle);
 </div>
 		
 <h4><a name="api:mono_gchandle_new">mono_gchandle_new</a></h4>
diff --git a/docs/sources/mono-api-jit.html b/docs/sources/mono-api-jit.html
index ee9836cd116..6651e32f917 100644
--- a/docs/sources/mono-api-jit.html
+++ b/docs/sources/mono-api-jit.html
@@ -1,16 +1,25 @@
 <h2>Synopsis</h2>
 
+	<p>These functions are used to get some runtime information
+	from the Just in Time compiler and also to control some
+	aspects of the initialization and shutdown of the runtime.
+	
 <div class="mapi-header">
+typedef struct _MonoJitInfo MonoJitInfo;
+
 @API_IDX@
 </div>
 
-<h3>JIT Information</h3>
-
+<h3>Just-in-Time Compiled Method Information</h3>
 
+	<p>Use the `MonoJitInfo` API to get data about a JITed
+	method.   These APIs are typically used by profiler modules
+	added to Mono.
+	
+<h4><a name="api:mono_jit_info_table_find">mono_jit_info_table_find</a></h4>
 <h4><a name="api:mono_jit_info_get_code_size">mono_jit_info_get_code_size</a></h4>
 <h4><a name="api:mono_jit_info_get_code_start">mono_jit_info_get_code_start</a></h4>
 <h4><a name="api:mono_jit_info_get_method">mono_jit_info_get_method</a></h4>
-<h4><a name="api:mono_jit_info_table_find">mono_jit_info_table_find</a></h4>
 
 <h3>Useful Debugging Functions</h3>
 
diff --git a/docs/sources/mono-api-methods.html b/docs/sources/mono-api-methods.html
index bd3e04759e9..3eac14009ad 100644
--- a/docs/sources/mono-api-methods.html
+++ b/docs/sources/mono-api-methods.html
@@ -162,7 +162,7 @@ If you want to invoke generic methods, you must call the method on the
 "inflated" class, which you can obtain from the
 <tt>mono_object_get_class()</tt>
 
-<div class="code">
+<div class="mapi-code">
 MonoClass *clazz;
 MonoMethod *method;
 
diff --git a/docs/sources/mono-api-object.html b/docs/sources/mono-api-object.html
index 92e8963dbf3..d11226f5232 100644
--- a/docs/sources/mono-api-object.html
+++ b/docs/sources/mono-api-object.html
@@ -45,7 +45,7 @@ typedef struct {
 @API_IDX@
 </div>
 
-	<p>MonoObject is the base definition for all managed objects
+	<p>`MonoObject` is the base definition for all managed objects
 	in the Mono runtime, it represents the <a
 	href="http://www.mono-project.com/monodoc/T:System.Object">System.Object</a>
 	managed type.
@@ -56,12 +56,11 @@ typedef struct {
 	following the pattern where the parent class is the first
 	field of a structure definition, for example:
 
-	<div class="code">
-	typedef struct {
-		MonoObject parent;
-		int my_new_field;
-	} MyNewObject
-	</div>
+	<div class="mapi-code">
+typedef struct {
+	MonoObject parent;
+	int my_new_field;
+} MyNewObject</div>
 
 <a name="objects"></a>
 <h2>Core Object Methods</h2>
@@ -71,7 +70,7 @@ typedef struct {
 	<p>For example, if you wanted to create an object of type
 	System.Version, you would use a piece of code like this:
 
-	<div class="code">
+<div class="mapi-code">
 MonoClass *version_class;
 MonoObject *result;
 
@@ -81,7 +80,7 @@ version_class = mono_class_from_name (mono_get_corlib (),
 
 /* Create an object of that class */
 result = mono_object_new (mono_domain_get (), version_class);
-	</div>
+</div>
 
 <h4><a name="api:mono_object_new_alloc_specific">mono_object_new_alloc_specific</a></h4>
 <h4><a name="api:mono_object_new_fast">mono_object_new_fast</a></h4>
@@ -116,19 +115,17 @@ result = mono_object_new (mono_domain_get (), version_class);
 	elements of type <tt>System.Byte</tt>, and sets the values
 	0xca and 0xfe on it:
 	
-	<pre class="code">
-
-	MonoArray *CreateByteArray (MonoDomain *domain)
-	{
-	    MonoArray *data;
+	<pre class="mapi-code">
+MonoArray *CreateByteArray (MonoDomain *domain)
+{
+    MonoArray *data;
 
-	    data = mono_array_new (domain, mono_get_byte_class (), 2);
-	    mono_array_set (data, guint8, 0, 0xca);
-	    mono_array_set (data, guint8, 0, 0xfe);
-
-	    return data;
-	}
+    data = mono_array_new (domain, mono_get_byte_class (), 2);
+    mono_array_set (data, guint8, 0, 0xca);
+    mono_array_set (data, guint8, 0, 0xfe);
 
+    return data;
+}
 	</pre>
 
 <h3>Creating Arrays</h3>
@@ -141,12 +138,31 @@ result = mono_object_new (mono_domain_get (), version_class);
 
 <h3>Using Arrays</h3>
 
+	<p>Arrays are represented by the `MonoArray` data type and are
+	instances of `MonoObject`.   While you can use the `bounds`
+	and `max_length` fields of the type, the actual storage
+	(represented by `vector`) is not very useful.   Instead you
+	should use one of the accesor methods described below to
+	fetch or set the values in the array.
+
+	<p>When setting values in an array, you should
+	use <a href="api:mono_array_set">mono_array_set</a> for
+	setting elements in an array that contains value types, and
+	<a
+	href="api:mono_array_setref">mono_array_setref</a> for arrays
+	that contain reference types. 
+	
+	<p>The <a href="api:mono_array_get">mono_array_get</a>,
+	<a href="api:mono_array_set">mono_array_set</a> and <a
+	href="api:mono_array_setref">mono_array_setref</a> are C
+	macros that wrap the underlying array access.   
+	
+<h4><a name="api:mono_array_get">mono_array_get</a></h4>
+<h4><a name="api:mono_array_length">mono_array_length</a></h4>
 <h4><a name="api:mono_array_set">mono_array_set</a></h4>
 <h4><a name="api:mono_array_setref">mono_array_setref</a></h4>
-<h4><a name="api:mono_array_length">mono_array_length</a></h4>
 <h4><a name="api:mono_array_addr">mono_array_addr</a></h4>
 <h4><a name="api:mono_array_addr_with_size">mono_array_addr_with_size</a></h4>
-<h4><a name="api:mono_array_get">mono_array_get</a></h4>
 <h4><a name="api:mono_array_element_size">mono_array_element_size</a></h4>
 
 <a name="fields"></a>
diff --git a/docs/sources/mono-api-string.html b/docs/sources/mono-api-string.html
index be70faf606a..9e0d6b4d830 100644
--- a/docs/sources/mono-api-string.html
+++ b/docs/sources/mono-api-string.html
@@ -17,10 +17,10 @@ typedef struct {
 	</div>
 
 	<p>All of the operations on strings are done on pointers to
-	MonoString objects, like this:
+	`MonoString` objects, like this:
 
-	<div class="code">
-	MonoString *hello = mono_string_new (mono_domain_get (), "hello, world");
+	<div class="mapi-code">
+MonoString *hello = mono_string_new (mono_domain_get (), "hello, world");
 	</div>
 
 	<p>Strings are bound to a particular application domain, which