diff options
| author | Miguel de Icaza <miguel@gnome.org> | 2016-02-03 21:18:42 +0300 |
|---|---|---|
| committer | Miguel de Icaza <miguel@gnome.org> | 2016-02-03 21:18:42 +0300 |
| commit | 6cfa9c7d6484c63e7e3afa5ed4696cdbf6fe2d6f (patch) | |
| tree | c2ce5bb1d27e30cf19f35a073cc210d3b832b7a6 /docs | |
| parent | b8462def3cff0b121cd9cbcf40fe11cc80fe2100 (diff) | |
[Runtime Documentation] More work on runtime documentation
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Makefile.am | 3 | ||||
| -rw-r--r-- | docs/exdoc | 31 | ||||
| -rw-r--r-- | docs/sources/mono-api-class.html | 25 | ||||
| -rw-r--r-- | docs/sources/mono-api-methods.html | 179 |
4 files changed, 198 insertions, 40 deletions
diff --git a/docs/Makefile.am b/docs/Makefile.am index bb90f1f2001..7c63214d4dc 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -17,10 +17,8 @@ EXTRA_DIST = \ check-exports \ check-coverage \ convert.cs \ - current-api \ deploy \ docs.make \ - documented \ embedded-api \ exdoc \ file-share-modes \ @@ -43,7 +41,6 @@ EXTRA_DIST = \ object-layout \ precise-gc \ produce-lists \ - public \ public-api \ README \ remoting \ diff --git a/docs/exdoc b/docs/exdoc index 4e60e1b90c7..ce35052443e 100644 --- a/docs/exdoc +++ b/docs/exdoc @@ -60,22 +60,26 @@ if ($html){ .api { padding: 10pt; margin: 10pt; + border: 3px solid #ddd; } .api-entry { border-bottom: none; - font-size: 120%; + font-size: 150%; + font-family: "Consolas", "Courier", monospace; + padding-bottom: .5em; } .prototype { border: 3px solid #ecf0f1; border-radius: 6px; - padding: 1em 1.2em; + padding: .5em; margin-top: 5pt; margin-bottom: 5pt; font-family: "Consolas", "Courier", monospace; display: block; overflow: auto; + background-color: #f9f9f9; } .header { @@ -93,12 +97,19 @@ if ($html){ white-space: pre; font-family: monospace; } + + .strike { + text-decoration: line-through; + } + .deprecated { + color: red; + } </style> </head> <body> EOF @a = split (/\n/, $files_content[$f]); - + $strikeextra = ""; for ($ai = 0; $ai < $#a; $ai++){ $line = $a[$ai]; @@ -106,9 +117,13 @@ EOF if ($api ne ""){ if ($api_shown == 1){ print OUT "</div>"; - if ($deprecated{$api}){ - print OUT "<p><b>DEPRECATED ${deprecated{$api}}</b>"; - } + if ($deprecated{$api}){ + $strike = "strike"; + $strikeextra = "</div><br><div class='deprecated'><b>Deprecated:</b> " . $deprecated{$api}; + } else { + $strike = ""; + $strikeextra = ""; + } } $api_shown = 1; $proto = $prototype{$api}; @@ -119,8 +134,8 @@ EOF print OUT<<EOF; <a name="api:$api"></a> <div class="api"> - <div class="api-entry">$api</div> - + <div class="api-entry $strike">$api$strikeextra</div> + <div><b>Syntax</b></div> <div class="prototype">$proto</div> <p> EOF diff --git a/docs/sources/mono-api-class.html b/docs/sources/mono-api-class.html index 328761577b8..1d5c47179ae 100644 --- a/docs/sources/mono-api-class.html +++ b/docs/sources/mono-api-class.html @@ -3,6 +3,16 @@ <p>The operations on <code>MonoClass*</code> allow you to query a number of properties of a .NET class from the C API. + <p>This page contains information + for <a href="#class-getting">how to obtain a MonoClass</a>, + how to <a href="#class-work">probe for different + features of a UonoClass</a> and APIs + to <a href="#class-members">access class members</a> and + <a href="#class-fields">access fields</a>. To access + methods, see the <a href="mono-api-methods.html">method + documentation API</a>. + +<a name="class-getting"> <h3>Getting a MonoClass</h3> <p>You typically would obtain a <code>MonoClass*</code> @@ -26,7 +36,7 @@ <h4><a name="api:mono_class_from_name">mono_class_from_name</a></h4> <h4><a name="api:mono_class_from_name_case">mono_class_from_name_case</a></h4> <h4><a name="api:mono_class_from_typeref">mono_class_from_typeref</a></h4> -<h4><a name="api:mono_class_from_typeref_checked">mono_class_from_typeref_checked</a> +<h4><a name="api:mono_class_from_typeref_checked">mono_class_from_typeref_checked</a></h4> <h4><a name="api:mono_class_from_generic_parameter">mono_class_from_generic_parameter</a></h4> <h3>Working with a MonoClass</h3> @@ -50,14 +60,14 @@ <h4><a name="api:mono_class_get_property_token">mono_class_get_property_token</a></h4> <h4><a name="api:mono_class_get_rank">mono_class_get_rank</a></h4> <h4><a name="api:mono_class_get_type">mono_class_get_type</a></h4> -<h4><a name="api:mono_class_get_type_token">mono_class_get_type_token</a> -<h4><a name="api:mono_class_implements_interface">mono_class_implements_interface</a> +<h4><a name="api:mono_class_get_type_token">mono_class_get_type_token</a></h4> +<h4><a name="api:mono_class_implements_interface">mono_class_implements_interface</a></h4> <h4><a name="api:mono_class_inflate_generic_method">mono_class_inflate_generic_method</a></h4> <h4><a name="api:mono_class_inflate_generic_type">mono_class_inflate_generic_type</a></h4> <h4><a name="api:mono_class_init">mono_class_init</a></h4> <h4><a name="api:mono_class_instance_size">mono_class_instance_size</a></h4> <h4><a name="api:mono_class_is_assignable_from">mono_class_is_assignable_from</a></h4> -<h4><a name="api:mono_class_is_delegate">mono_class_is_delegate</a> +<h4><a name="api:mono_class_is_delegate">mono_class_is_delegate</a></h4> <h4><a name="api:mono_class_is_enum">mono_class_is_enum</a></h4> <h4><a name="api:mono_class_is_subclass_of">mono_class_is_subclass_of</a></h4> <h4><a name="api:mono_class_is_valuetype">mono_class_is_valuetype</a></h4> @@ -70,6 +80,7 @@ <h4><a name="api:mono_class_value_size">mono_class_value_size</a></h4> <h4><a name="api:mono_class_vtable">mono_class_vtable</a></h4> +<a name="class-members"> <h3>Getting Class Members</h3> <h4><a name="api:mono_class_get_fields">mono_class_get_fields</a></h4> @@ -82,14 +93,16 @@ <h4><a name="api:mono_class_get_property_from_name">mono_class_get_property_from_name</a></h4> <h4><a name="api:mono_class_get_events">mono_class_get_events</a></h4> +<a name="class-fields"> <h3>Fields</h3> <h4><a name="api:mono_field_get_data">mono_field_get_data</a></h4> <h4><a name="api:mono_field_get_offset">mono_field_get_offset</a></h4> <h4><a name="api:mono_field_full_name">mono_field_full_name</a></h4> -<h3>Methods</h3> +<h3>Method Accessibility</h3> -<h4><a name="api:mono_get_inflated_method">mono_get_inflated_method</a></h4> <h4><a name="api:mono_method_can_access_field">mono_method_can_access_field</a></h4> <h4><a name="api:mono_method_can_access_method">mono_method_can_access_method</a></h4> + +<p> diff --git a/docs/sources/mono-api-methods.html b/docs/sources/mono-api-methods.html index f8ea4e0493c..ae12de2fbb5 100644 --- a/docs/sources/mono-api-methods.html +++ b/docs/sources/mono-api-methods.html @@ -1,41 +1,141 @@ -<h3>Methods</h3> +<h2>Methods</h2> -<h3>Invoking Methods</h3> + <p>Methods are represented by the <code>MonoMethod*</code> + instances. Various APIs surface these instances, but usually + you will use the <a href="#method-desc">method description</a> + API to get a handle to a Mono Method. You can <a href="method-invoking">invoke</a> those methods from C, + or you can probe <a href="method-working">probe various properties</a> of a method, and in particular + its <a href="method-signature">method signature</a> or get + some <a href="method-header">low-level information</a> about them. -<h4><a name="api:mono_runtime_invoke">mono_runtime_invoke</a></h4> + <p>The following code snippet from the Mono runtime shows you + how to create a managed <code>System.Version</code> instance + with four integers by looking up the constructor in the + managed implementation of System.Version, creating an instance + of the object, and then invoking the constructor on it. -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="header"> +MonoObject* +create_version (MonoDomain *domain, guint32 major, guint32 minor, guint32 build, guint32 revision) +{ + MonoClass *System_Version; + MonoMethod *create_version; + MonoError error; + MonoObject *result; + gpointer args [4]; -<div class="code"> -MonoClass *clazz; -MonoMethod *method; + System_Version = mono_class_from_name (mono_defaults.corlib, "System", "Version"); -clazz = mono_object_get_class (obj); + // Create a method description that we use to search for the + // constructor method + MonoMethodDesc *desc = mono_method_desc_new (":.ctor(int,int,int,int)", FALSE); + create_version = mono_method_desc_search_in_class (desc, System_Version); + mono_method_desc_free (desc); -/* - * If there are more Add methods declared, you - * may use mono_method_desc_search_in_class (clazz, ":Add(T)"), - * you must substitute ":Add(T)" with the correct type, for example - * for List<int>, you would use ":Add(int)". - */ -method = mono_class_get_method_from_name (clazz, "Add", 1); -mono_runtime_invoke (method, obj, args, &exception); -</div> + // Setup the parameters to pass. + args [0] = &major; + args [1] = &minor; + args [2] = &build; + args [3] = &revision; + // Create the object instance + result = mono_object_new_checked (domain, System_Version, &error); -<h4><a name="api:mono_runtime_invoke_array">mono_runtime_invoke_array</a></h4> -<h4><a name="api:mono_runtime_delegate_invoke">mono_runtime_delegate_invoke</a></h4> + // Raise an exception in case of an error + mono_error_raise_exception (&error); -<h4><a name="api:mono_method_body_get_object">mono_method_body_get_object</a></h4> + // Otherwise, invoke the constructor + mono_runtime_invoke (create_version, result, args, NULL); + + // Return ther esult + return result; +} + + </div> + +<a name="method-desc"></a> +<h3>Method Descriptions</h3> + + <p>Methods are represented by the <code>MonoMethod*</code> + instances. To simplify the process of getting + a <code>MonoMethod*</code>, you use Method Descriptors, which + are C-strings that describe the method that you are looking + for, and then you perform a search in either + a <a href="mono-api-type.html">type</a>, or a + loaded <a href="mono-api-image.html">image</a>. + + + <p>To describe a method, you use the Method Description API. + Method descriptions are used to locate a method in the + executing program. They can either be fully specified, that + is, they would include the namespace, class, method name and + all of its arguments or they omit the namespace and arguments + and even use wildcard matches for the class name and method names. + + <p>You use the fully specified version to identify a + particular method, or you can use the partial version to find + a method or a family of methods in the code. + + <p>Method descriptions are typically created from a C string + representation, and take the following form: + + <p><code>[namespace.]classname:methodname[(args...)]</code> + + <p>Both classname and methodname can contain the '*' character + which can be used to match anything. Arguments are separated + by commas. + + <p>You can use the type shortcuts to match the fully qualified + parameter types. The supported type shortcuts are: + <code>char</code>, + <code>bool</code>, + <code>byte</code>, + <code>sbyte</code>, + <code>uint16</code>, + <code>int16</code>, + <code>uint</code>, + <code>int</code>, + <code>ulong</code>, + <code>long</code>, + <code>uintptr</code>, + <code>intptr</code>, + <code>single</code>, + <code>double</code>, + <code>string</code> and + <code>object</code>. + + <p>The type parameters can use the "&" and "*" type modifiers. + + <p>Examples of method descriptions: + <ul> + <li>"Monitor:Exit": matches classes and methods called "Monitor.Exit" + <li>"Monitor:enter_with_atomic_var(object,bool&)": + matches a method in the class Monitor with two + specific type parameters. + <li>":.ctor(int,int,int,int)": matches constructors + that take four integers. + <li>"System.Globalization.CultureInfo:CreateCulture(string,bool)": + matches the CreateCultureMethod that takes a string + and a boolean on the System.Globalization.CultureInfo class. + </ul> + + <p>You can + then <a href="api:mono_method_desc_search_in_image">search for + methods in MonoImages</a> + or <a href="api:mono_method_desc_search_in_class">search for + methods in classes</a>. + +<h4><a name="api:mono_method_desc_new">mono_method_desc_new</a></h4> <h4><a name="api:mono_method_desc_free">mono_method_desc_free</a></h4> <h4><a name="api:mono_method_desc_from_method">mono_method_desc_from_method</a></h4> <h4><a name="api:mono_method_desc_full_match">mono_method_desc_full_match</a></h4> <h4><a name="api:mono_method_desc_match">mono_method_desc_match</a></h4> -<h4><a name="api:mono_method_desc_new">mono_method_desc_new</a></h4> <h4><a name="api:mono_method_desc_search_in_class">mono_method_desc_search_in_class</a></h4> <h4><a name="api:mono_method_desc_search_in_image">mono_method_desc_search_in_image</a></h4> + +<a name="method-working"></a> +<h3>Working with Methods</h3> + <h4><a name="api:mono_method_full_name">mono_method_full_name</a></h4> <h4><a name="api:mono_method_get_class">mono_method_get_class</a></h4> <h4><a name="api:mono_method_get_flags">mono_method_get_flags</a></h4> @@ -53,6 +153,38 @@ mono_runtime_invoke (method, obj, args, &exception); <h4><a name="api:mono_method_has_marshal_info">mono_method_has_marshal_info</a></h4> <h4><a name="api:mono_method_verify">mono_method_verify</a></h4> +<a name="method-invoking"></a> +<h3>Invoking Methods</h3> + +<h4><a name="api:mono_runtime_invoke">mono_runtime_invoke</a></h4> + +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"> +MonoClass *clazz; +MonoMethod *method; + +clazz = mono_object_get_class (obj); + +/* + * If there are more Add methods declared, you + * may use mono_method_desc_search_in_class (clazz, ":Add(T)"), + * you must substitute ":Add(T)" with the correct type, for example + * for List<int>, you would use ":Add(int)". + */ +method = mono_class_get_method_from_name (clazz, "Add", 1); +mono_runtime_invoke (method, obj, args, &exception); +</div> + + +<h4><a name="api:mono_runtime_invoke_array">mono_runtime_invoke_array</a></h4> +<h4><a name="api:mono_runtime_delegate_invoke">mono_runtime_delegate_invoke</a></h4> + +<h4><a name="api:mono_method_body_get_object">mono_method_body_get_object</a></h4> + +<a name="method-signature"></a> <h3>Method Signatures</h3> <h4><a name="api:mono_method_signature">mono_method_signature</a></h4> @@ -70,6 +202,7 @@ mono_runtime_invoke (method, obj, args, &exception); <h4><a name="api:mono_get_method_full">mono_get_method_full</a></h4> <h4><a name="api:mono_get_method">mono_get_method</a></h4> +<a name="method-header"></a> <h3>Methods Header Operations</h3> <h4><a name="api:mono_method_get_header">mono_method_get_header</a></h4> |