--- /dev/null
+2006-11-19 Miguel de Icaza <miguel@novell.com>
+
+ * exdoc: Move to use CSS instead of tables, this will break
+ GtkHTML rendering.
+
+ * ignore: Updated with more hidden APIs.
+
+ * Bunch of documentation work.
+
all: monoapi.tree
monoapi.tree: toc.xml
+ cp api-style.css deploy
mdassembler --out monoapi --hb toc.xml
extract: convert.exe
mcs convert.cs -r:AgilityPack.dll
install:
- cp monoapi.* `monodoc --get-sourcesdir`
+ cp monoapi.* `pkg-config monodoc --variable=sourcesdir`
$files[$filecount] = $n;
while (<IN>){
@files_content[$filecount] .= $_;
+ if (/name="api:(.*?)"/){
+ $_ =~ s/.*name="api:(\w+?)".*/\1/;
+ $apis[$filecount] .= "$_";
+ }
}
$filecount++;
close IN;
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>$name</title>
+ <style type="text/css">
+ h3 {
+ font-size: 18px;
+ padding-bottom: 4pt;
+ border-bottom: 2px solid #dddddd;
+ }
+
+ .api {
+ border: 1px solid;
+ padding: 10pt;
+ margin: 10pt;
+ }
+
+ .api-entry {
+ border-bottom: none;
+ font-size: 18px;
+ }
+
+ .prototype {
+ border: 1px solid;
+ background-color: #f2f2f2;
+ padding: 5pt;
+ margin-top: 5pt;
+ margin-bottom: 5pt;
+ }
+
+ .header {
+ border: 1px solid;
+ padding: 0 0 5pt 5pt;
+ margin: 10pt;
+ white-space: pre;
+ font-family: monospace;
+ }
+
+ .code {
+ border: 1px solid;
+ padding: 0 0 5pt 5pt;
+ margin: 10pt;
+ white-space: pre;
+ font-family: monospace;
+ }
+ </style>
</head>
<body>
EOF
for ($ai = 0; $ai < $#a; $ai++){
$line = $a[$ai];
-
+
($api,$caption) = $line =~ /<h4><a name=\"api:(\w+)\">(\w+)<\/a><\/h4>/;
if ($api ne ""){
$proto = $prototype{$api};
}
print OUT<<EOF;
-<blockquote>
+ <div class="api">
<a name="api:$api"></a>
- <table summary="" class="HeaderTable" width="100%" cellpadding="5">
- <tr bgcolor="#b0c4de"><td>
- <h3 class="api">$api</h3>
- </td></tr>
- </table>
-
- <blockquote>
- <table summary="" class="SignatureTable" bgcolor="#c0c0c0" cellspacing="0" width="100%">
- <tr><td>
- <table summary="" class="InnerSignatureTalbe" cellpadding="10" cellspacing="0" width="100%">
- <tr bgcolor="#f2f2f2"><td>
- <h4>$proto</h4>
- </td></tr>
- </table>
- </td></tr>
- </table>
- </blockquote>
+ <div class="api-entry">$api</div>
+
+ <div class="prototype">$proto</div>
<p>
EOF
- if ($arguments{$api} ne ""){
- print OUT "<h4>Parameters</h4>";
- print OUT "<blockquote><dl>";
-
- print OUT "$arguments{$api}\n";
- print OUT "</dl></blockquote>";
- }
- if ($returns{$api} ne ""){
- print OUT "<h4>Returns</h4>";
- print OUT "<blockquote>";
- print OUT "$returns{$api}\n";
- print OUT "</blockquote>";
- }
- if ($bodies{$api} ne ""){
- print OUT "<h4>Remarks</h4>";
- print OUT "<blockquote>";
- print OUT "$bodies{$api}\n";
- print OUT "</blockquote>";
- }
+ &opt_print ("Parameters", $arguments{$api});
+ &opt_print ("Remarks", $bodies{$api});
+ &opt_print ("Returns", $returns{$api});
print OUT "\n";
- print OUT "</blockquote>";
+ print OUT "</div>";
} else {
+ if ($line =~ /@API_IDX@/){
+ $apis_toc = &create_toc ($apis[$f]);
+ $line =~ s/\@API_IDX\@/$apis_toc/;
+ }
+
print OUT "$line\n";
}
}
</html>
EOF
close OUT;
- system ("mono convert.exe $dir/html/$name $dir/deploy/$name");
+ system ("mono convert.exe $dir/html/$name $dir/html/x-$name");
+
+ # clean up the mess that AgilityPack does, it CDATAs our CSS
+ open HACK, "$dir/html/x-$name" || die "Could not open $dir/html/x-$name";
+ open HACKOUT, ">$dir/deploy/$name" || die "Could not open output";
+
+ while (<HACK>){
+ s/^\/\/<!\[CDATA\[//;
+ s/^\/\/\]\]>\/\///;
+ print HACKOUT $_;
+ }
+ #system ("cp.exe $dir/html/$name $dir/deploy/$name");
}
}
$returns =~ s/[@#](\w+)/<i>\1<\/i>/g;
$args =~ s/@(\w+)/<i>\1<\/i>/g;
+ $body =~ s/\n/ /;
$bodies{$func} = $body;
$arguments{$func} = $args;
$returns{$func} = $returns;
last if (/\{/);
}
$proto =~ s/{//;
+ # clean it up a little, remove newlines, empty space at end
+ $proto =~ s/ +$//;
+ # Turn "Type * xxx" into "Type* xxx"
+ $proto =~ s/^(\w+)\W+\*/\1\*/;
$prototype{$func} = $proto;
return;
}
$inbody = 1;
}
} elsif ($inbody == 1) {
- if (/Returns:/){
- s/Returns://;
+ if (/Returns?:/){
+ s/Returns?://;
$returns = "\t$_\n";
$inbody = 2;
} else {
}
}
+
+sub create_toc {
+ my ($apis_listed) = @_;
+ my $type_size = 0;
+ my $name_size = 0;
+ my $ret, $xname, $args, $line;
+ $apis_toc = "";
+
+
+ # Try to align things, so compute type size, method size, and arguments
+ foreach $line (split /\n/, $apis_listed){
+ $p = $prototype{$line};
+ ($ret, $xname, $args) = $p =~ /(.*)\n(\w+)[ \t](.*)/;
+ $tl = length ($ret);
+ $pl = length ($xname);
+
+ $type_size = $tl if ($tl > $type_size);
+ $name_size = $pl if ($pl > $name_size);
+ }
+
+ $type_size++;
+ $name_size++;
+
+ foreach $line (split /\n/, $apis_listed){
+ chop;
+ $p = $prototype{$line};
+ ($ret, $xname, $args) = $p =~ /(.*)\n(\w+)[ \t](.*)/;
+
+ $rspace = " " x ($type_size - length ($ret));
+ $nspace = " " x ($name_size - length ($xname));
+ $args = &format ($args, length ($ret . $rspace . $xname . $nspace), 60);
+ $apis_toc .= "$ret$rspace<a href=\"\#api:$line\">$xname</a>$nspace$args\n";
+ }
+ return $apis_toc;
+}
+
+#
+# Formats the rest of the arguments in a way that will fit in N columns
+#
+sub format {
+ my ($args, $size, $limit) = @_;
+ my $sret = "";
+
+# return $args if ((length (args) + size) < $limit);
+
+ $remain = $limit - $size;
+ @sa = split /,/, $args;
+ $linelen = $size;
+ foreach $arg (@sa){
+ if ($sret eq ""){
+ $sret = $arg . ", ";
+ $linelen += length ($sret);
+ } else {
+ if ($linelen + length ($arg) < $limit){
+ $sret .= "FITS" . $arg . ", ";
+ } else {
+ $newline = " " x ($size) . $arg . ", ";
+ $linelen = length ($newline);
+ $sret .= "\n" . $newline;
+ }
+ }
+ }
+ $sret =~ s/, $/;/;
+ return $sret;
+}
+
+sub opt_print {
+ my ($caption, $opttext) = @_;
+
+ if ($opttext ne "" && (!($opttext =~ /^[ \t]+$/))){
+ print OUT "<b>$caption</b>\n";
+ print OUT "<blockquote>$opttext</blockquote>\n";
+ }
+}
# library dependencies but could be private
#
mono_assembly_load_corlib
+mono_assembly_load_from
mono_jit_walk_stack
mono_init_icall
mono_eval_cond_branch
mono_ssa_deadce
mono_find_spvar_for_region
mono_add_varcopy_to_end
+mono_image_build_metadata
#
# JIT code genreation internals
#
mini_init
mini_cleanup
mono_metadata_compute_table_bases
+mono_image_basic_init
+mono_image_create_method_token
+mono_image_create_pefile
+mono_image_insert_strings
+mono_image_load_module
+mono_image_add_to_name_cache
+mono_image_verify_tables
mono_debug_init_1
mono_debug_init_2
mono_debug_init
+<h2>Assemblies</h2>
+
+<h3>Synopsis</h3>
+
+ <div class="header">
+#include <metadata/assembly.h>
+
+typedef struct _MonoImage MonoImage;
+typedef struct _MonoAssembly MonoAssembly;
+
+typedef struct {
+ const char *name;
+ const char *culture;
+ const char *hash_value;
+ const guint8* public_key;
+ guchar public_key_token [MONO_PUBLIC_KEY_TOKEN_LENGTH];
+ guint32 hash_alg;
+ guint32 hash_len;
+ guint32 flags;
+ guint16 major, minor, build, revision;
+} MonoAssemblyName;
+
+@API_IDX@
+
+ </div>
+
<h3>Assembly Loading</h3>
<h4><a name="api:mono_assembly_open">mono_assembly_open</a></h4>
<h4><a name="api:mono_assembly_close">mono_assembly_close</a></h4>
<h4><a name="api:mono_assembly_load">mono_assembly_load</a></h4>
-<h4><a name="api:mono_assembly_load_from">mono_assembly_load_from</a></h4>
<h4><a name="api:mono_assembly_load_full">mono_assembly_load_full</a></h4>
<h4><a name="api:mono_assembly_loaded">mono_assembly_loaded</a></h4>
<h3>Assembly Names</h3>
+ <p>The MonoAssemblyName contains the full identity of an
+ assembly (name, culture, public key, public key token,
+ version and any other flags).
+
+ <p>These unmanaged objects represent the <a
+ href="http://www.mono-project.com/monodoc/T:System.Reflection.AssemblyName">System.Reflection.AssemblyName</a>
+ managed type.
+
<h4><a name="api:mono_assembly_name_parse">mono_assembly_name_parse</a></h4>
<h4><a name="api:mono_assembly_name_free">mono_assembly_name_free</a></h4>
<h4><a name="api:mono_stringify_assembly_name">mono_stringify_assembly_name</a></h4>
+<h2>Application Domains</h2>
+
+<h3>Synopsis</h3>
+
+<div class="header">
+#include <metadata/appdomain.h>
+
+/* Managed AppDomain */
+typedef struct _MonoAppDomain MonoAppDomain;
+
+/* Unmanaged representation */
+typedef struct _MonoDomain MonoDomain;
+
+/* Represents System.Runtime.Remoting.Contexts.Context */
+typedef struct _MonoAppContext MonoAppContext
+@API_IDX@
+</div>
+
+ <p>Application domains are used to isolate multiple
+ applications on a single Mono virtual machine. They are
+ conceptually similiar to processes, the difference is that
+ processes are managed by the operating system, while
+ application domains are managed by the Mono virtual machine.
+
+ <p>For more information on applications domains see the <a
+ href="http://www.gotdotnet.com/team/clr/AppdomainFAQ.aspx">AppDomain FAQ</a>.
+
+ <p>The <tt>MonoDomain</tt> is the unmanaged representation of
+ the <a
+ href="http://www.mono-project.com/monodoc/T:System.AppDomain">System.AppDomain</a>
+ managed type, while the <tt>MonoAppDomain</tt> type represents
+ the managed version (<tt>MonoAppDomain</tt> has a pointer to
+ a <tt>MonoDomain</tt>).
+
<h4><a name="api:mono_domain_assembly_open">mono_domain_assembly_open</a></h4>
<h4><a name="api:mono_domain_create">mono_domain_create</a></h4>
<h4><a name="api:mono_domain_finalize">mono_domain_finalize</a></h4>
<h4><a name="api:mono_domain_get_tls_key">mono_domain_get_tls_key</a></h4>
<h4><a name="api:mono_domain_owns_vtable_slot">mono_domain_owns_vtable_slot</a></h4>
+<h3>Contexts</h3>
+
<h4><a name="api:mono_context_get">mono_context_get</a></h4>
<h4><a name="api:mono_context_set">mono_context_set</a></h4>
<h2>Exception Handling</h2>
+<div class="header">
+@API_IDX@
+</div>
+
<h3>Raising and Catching exceptions</h3>
<h4><a name="api:mono_raise_exception">mono_raise_exception</a></h4>
<h3>Obtaining Common Exceptions</h3>
+ <p>There are a number of common exceptions that are used by
+ the runtime, use the routines in this section to get a copy of
+ those exceptions.
+
<h4><a name="api:mono_get_exception_appdomain_unloaded">mono_get_exception_appdomain_unloaded</a></h4>
<h4><a name="api:mono_get_exception_argument">mono_get_exception_argument</a></h4>
<h4><a name="api:mono_get_exception_argument_null">mono_get_exception_argument_null</a></h4>
-<h1>GC Hnadles</h1>
+<h1>GC Handles</h1>
+<h3>Synopsys</h3>
+
+ <div class="header">
+@API_IDX@
+ </div>
+
<p>GC handles are wrappers that are used to keep references to
managed objects in the unmanaged space and preventing the
object from being disposed.
<ul>
<li>Handles to objects (use <tt><a
- href="api:mono_gchandle_new">mono_gchandle_new</a></tt>).
+ href="#api:mono_gchandle_new">mono_gchandle_new</a></tt>).
<li>Weak handles to objects (use <tt><a
- href="api:mono_gchandle_new_weakref">mono_gchandle_new_weakref</a></tt>).
+ href="#api:mono_gchandle_new_weakref">mono_gchandle_new_weakref</a></tt>).
Weak handles can have the objects reclaimed by the
garbage collector.
<tt>mono_gchandle_get_target</tt>.
<p>For example, consider the following C code:
-<pre>
+<div class="code">
static MonoObject* o = NULL;
-</pre>
+</div>
<p>The object in `o' will *NOT* be scanned.
it from being collected, you need to acquire a GC handle for
it.
-<pre>
+<div class="code">
guint32 handle = mono_gchandle_new (my_object, TRUE);
-</pre>
+</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:
-<pre>
+<div class="code">
MonoObject* obj = mono_gchandle_get_target (handle);
-</pre>
+</div>
<p>When you don't need the handle anymore you need to call:
-<pre>
+<div class="code">
mono_gchandle_free (handle);
-</pre>
+</div>
<p>Note that if you assign a new object to the C var, you need
to get a new handle, it's not enough to store a new object in
<p>So code that looked like this:
-<pre>
+<div class="code">
static MonoObject* o = NULL;
...
o = mono_object_new (...);
...
/* when done to allow the GC to collect o */
o = NULL;
-</pre>
+</div>
<p>should now be changed to:
-<pre>
+<div class="code">
static guint32 o_handle;
...
MonoObject *o = mono_object_new (...);
...
/* when done to allow the GC to collect o */
mono_gchandle_free (o_handle);
-</pre>
+</div>
<h4><a name="api:mono_gchandle_new">mono_gchandle_new</a></h4>
<h4><a name="api:mono_gchandle_new_weakref">mono_gchandle_new_weakref</a></h4>
<p>Images are the component of assemblies that actually hold
the CIL code in the extended PE/COFF file.
+<h3>Synopsis</h3>
-<h4><a name="api:mono_image_addref">mono_image_addref</a></h4>
-<h4><a name="api:mono_image_add_to_name_cache">mono_image_add_to_name_cache</a></h4>
+ <div class="header">
+#include <metadata/image.h>
+
+typedef struct _MonoImage MonoImage;
+typedef enum {
+ MONO_IMAGE_OK,
+ MONO_IMAGE_ERROR_ERRNO,
+ MONO_IMAGE_MISSING_ASSEMBLYREF,
+ MONO_IMAGE_IMAGE_INVALID
+} MonoImageOpenStatus;
+
+@API_IDX@
+ </div>
+
+<h3>Image APIs</h3>
+
+ <p>Images are the actual elements in the runtime that contain
+ the actual code being executed.
+
+<h3>Opening and closing MonoImages</h3>
+
+<h4><a name="api:mono_image_open">mono_image_open</a></h4>
+<h4><a name="api:mono_image_open_full">mono_image_open_full</a></h4>
+<h4><a name="api:mono_image_open_from_data">mono_image_open_from_data</a></h4>
+<h4><a name="api:mono_image_open_from_data_full">mono_image_open_from_data_full</a></h4>
<h4><a name="api:mono_image_close">mono_image_close</a></h4>
-<h4><a name="api:mono_image_ensure_section_idx">mono_image_ensure_section_idx</a></h4>
-<h4><a name="api:mono_image_ensure_section">mono_image_ensure_section</a></h4>
+<h4><a name="api:mono_image_addref">mono_image_addref</a></h4>
+<h4><a name="api:mono_image_load_file_for_image">mono_image_load_file_for_image</a></h4>
+
+<h3>Image Information</h3>
+
+<h4><a name="api:mono_image_get_guid">mono_image_get_guid</a></h4>
<h4><a name="api:mono_image_get_assembly">mono_image_get_assembly</a></h4>
<h4><a name="api:mono_image_get_entry_point">mono_image_get_entry_point</a></h4>
<h4><a name="api:mono_image_get_filename">mono_image_get_filename</a></h4>
<h4><a name="api:mono_image_get_name">mono_image_get_name</a></h4>
-<h4><a name="api:mono_image_get_public_key">mono_image_get_public_key</a></h4>
<h4><a name="api:mono_image_get_resource">mono_image_get_resource</a></h4>
-<h4><a name="api:mono_image_get_strong_name">mono_image_get_strong_name</a></h4>
<h4><a name="api:mono_image_get_table_info">mono_image_get_table_info</a></h4>
<h4><a name="api:mono_image_get_table_rows">mono_image_get_table_rows</a></h4>
-<h4><a name="api:mono_image_has_authenticode_entry">mono_image_has_authenticode_entry</a></h4>
<h4><a name="api:mono_image_is_dynamic">mono_image_is_dynamic</a></h4>
<h4><a name="api:mono_image_loaded_by_guid">mono_image_loaded_by_guid</a></h4>
<h4><a name="api:mono_image_loaded">mono_image_loaded</a></h4>
-<h4><a name="api:mono_image_load_file_for_image">mono_image_load_file_for_image</a></h4>
<h4><a name="api:mono_image_lookup_resource">mono_image_lookup_resource</a></h4>
-<h4><a name="api:mono_image_open_from_data">mono_image_open_from_data</a></h4>
-<h4><a name="api:mono_image_open">mono_image_open</a></h4>
-<h4><a name="api:mono_image_rva_map">mono_image_rva_map</a></h4>
<h4><a name="api:mono_image_strerror">mono_image_strerror</a></h4>
+
+<h3>Public Keys, Strong Names and Certificates</h3>
+
<h4><a name="api:mono_image_strong_name_position">mono_image_strong_name_position</a></h4>
-<h4><a name="api:mono_image_verify_tables">mono_image_verify_tables</a></h4>
-<h4><a name="api:mono_image_get_guid">mono_image_get_guid</a></h4>
-<h4><a name="api:mono_image_open_from_data_full">mono_image_open_from_data_full</a></h4>
-<h4><a name="api:mono_image_open_full">mono_image_open_full</a></h4>
+<h4><a name="api:mono_image_get_public_key">mono_image_get_public_key</a></h4>
+<h4><a name="api:mono_image_get_strong_name">mono_image_get_strong_name</a></h4>
+<h4><a name="api:mono_image_has_authenticode_entry">mono_image_has_authenticode_entry</a></h4>
-<h3>Reflection.Emit Related APIs</h3>
-
- <p>These are internal routines of the Mono VM for the
- implementation of Reflection.Emit and are not likely of use
- for developers.
-
-<h4><a name="api:mono_image_basic_init">mono_image_basic_init</a></h4>
-<h4><a name="api:mono_image_build_metadata">mono_image_build_metadata</a></h4>
-<h4><a name="api:mono_image_create_method_token">mono_image_create_method_token</a></h4>
-<h4><a name="api:mono_image_create_pefile">mono_image_create_pefile</a></h4>
-<h4><a name="api:mono_image_create_token">mono_image_create_token</a></h4>
-<h4><a name="api:mono_image_insert_string">mono_image_insert_string</a></h4>
-<h4><a name="api:mono_image_load_module">mono_image_load_module</a></h4>
+<h3>Low-level features</h3>
+
+<h4><a name="api:mono_image_rva_map">mono_image_rva_map</a></h4>
+<h4><a name="api:mono_image_ensure_section_idx">mono_image_ensure_section_idx</a></h4>
+<h4><a name="api:mono_image_ensure_section">mono_image_ensure_section</a></h4>
-<h2>Native Code Generation APIs</h2>
+<h2>Synopsis</h2>
- <p>These APIs are only available when Mono is running with the
- native code generation backend (the Mono JIT).
+<div class="header">
+@API_IDX@
+</div>
<h3>Useful Debugging Functions</h3>
a debugger.
<h4><a name="api:mono_pmip">mono_pmip</a></h4>
-<h4><a name="api:mono_print_code">mono_print_code</a></h4>
<h4><a name="api:mono_print_method_from_ip">mono_print_method_from_ip</a></h4>
<h4><a name="api:mono_print_thread_dump">mono_print_thread_dump</a></h4>
<h4><a name="api:mono_threads_request_thread_dump">mono_threads_request_thread_dump</a></h4>
<h4><a name="api:mono_inst_name">mono_inst_name</a></h4>
-
<h2>Strings</h2>
- <p>Strings inside the Mono runtime are represented with the
- MonoString structure, which is:
+ <p>Strings representation inside the Mono runtime.
- <pre class="code">
-
- typedef struct {
- MonoObject object;
- gint32 length;
- gunichar2 chars [0];
- } MonoString;
+<h3>Synopsis</h3>
+
+ <div class="header">
+#include <metadata/object.h>
+
+typedef struct {
+ MonoObject object;
+ gint32 length;
+ gunichar2 chars [0];
+} MonoString;
- </pre>
+ </div>
<p>All of the operations on strings are done on pointers to
MonoString objects, like this:
- <pre class="code">
+ <div class="code">
MonoString *hello = mono_string_new (mono_domain_get (), "hello, world");
- </pre>
+ </div>
<p>Strings are bound to a particular application domain, which
is why it is necessary to pass a MonoDomain argument as the
projects / mono.git / commitdiff