[docs] Update formatting in mono-api-internal.
authorJon Purdy <evincarofautumn@gmail.com>
Thu, 9 Mar 2017 21:23:27 +0000 (13:23 -0800)
committerJon Purdy <evincarofautumn@gmail.com>
Fri, 24 Mar 2017 20:43:07 +0000 (13:43 -0700)
mono/metadata/loader.c
mono/metadata/marshal.c
mono/metadata/remoting.c
mono/metadata/sgen-mono.c
mono/sgen/sgen-descriptor.c

index 67576b90bf0d2d24ba9734c4c6e6a309db50cbb4..6476c23269ac2256c84b323a727d335929653b36 100644 (file)
@@ -2261,7 +2261,7 @@ static gboolean loader_lock_track_ownership = FALSE;
 /**
  * mono_loader_lock:
  *
- * See docs/thread-safety.txt for the locking strategy.
+ * See \c docs/thread-safety.txt for the locking strategy.
  */
 void
 mono_loader_lock (void)
@@ -2272,6 +2272,9 @@ mono_loader_lock (void)
        }
 }
 
+/**
+ * mono_loader_unlock:
+ */
 void
 mono_loader_unlock (void)
 {
index c794ccc053572343ccb6ad68e7692d81130da7ec..c639bda2efe31db3a121a7354096e9c535b910f2 100644 (file)
@@ -2798,6 +2798,9 @@ mono_mb_create_and_cache (GHashTable *cache, gpointer key,
        return mono_mb_create_and_cache_full (cache, key, mb, sig, max_stack, NULL, NULL);
 }
 
+/**
+ * mono_marshal_method_from_wrapper:
+ */
 MonoMethod *
 mono_marshal_method_from_wrapper (MonoMethod *wrapper)
 {
@@ -3078,6 +3081,9 @@ cache_generic_delegate_wrapper (GHashTable *cache, MonoMethod *orig_method, Mono
        return res;
 }
 
+/**
+ * mono_marshal_get_delegate_begin_invoke:
+ */
 MonoMethod *
 mono_marshal_get_delegate_begin_invoke (MonoMethod *method)
 {
@@ -3314,6 +3320,9 @@ mono_mb_emit_restore_result (MonoMethodBuilder *mb, MonoType *return_type)
 
 #endif /* DISABLE_JIT */
 
+/**
+ * mono_marshal_get_delegate_end_invoke:
+ */
 MonoMethod *
 mono_marshal_get_delegate_end_invoke (MonoMethod *method)
 {
@@ -3761,8 +3770,9 @@ mono_marshal_get_delegate_invoke_internal (MonoMethod *method, gboolean callvirt
        return res;     
 }
 
-/*
- * the returned method invokes all methods in a multicast delegate.
+/**
+ * mono_marshal_get_delegate_invoke:
+ * The returned method invokes all methods in a multicast delegate.
  */
 MonoMethod *
 mono_marshal_get_delegate_invoke (MonoMethod *method, MonoDelegate *del)
@@ -4212,15 +4222,17 @@ emit_runtime_invoke_body (MonoMethodBuilder *mb, MonoImage *image, MonoMethod *m
 }
 #endif
 
-/*
- * generates IL code for the runtime invoke function 
- * MonoObject *runtime_invoke (MonoObject *this_obj, void **params, MonoObject **exc, void* method)
+/**
+ * mono_marshal_get_runtime_invoke:
+ * Generates IL code for the runtime invoke function:
  *
- * we also catch exceptions if exc != null
- * If VIRTUAL is TRUE, then METHOD is invoked virtually on THIS. This is useful since
- * it means that the compiled code for METHOD does not have to be looked up 
+ * <code>MonoObject *runtime_invoke (MonoObject *this_obj, void **params, MonoObject **exc, void* method)</code>
+ *
+ * We also catch exceptions if \p exc is not NULL.
+ * If \p virtual is TRUE, then \p method is invoked virtually on \p this. This is useful since
+ * it means that the compiled code for \p method does not have to be looked up 
  * before calling the runtime invoke wrapper. In this case, the wrapper ignores
- * its METHOD argument.
+ * its \p method argument.
  */
 MonoMethod *
 mono_marshal_get_runtime_invoke (MonoMethod *method, gboolean virtual_)
@@ -4634,9 +4646,10 @@ mono_mb_emit_auto_layout_exception (MonoMethodBuilder *mb, MonoClass *klass)
 }
 #endif
 
-/*
- * generates IL code for the icall wrapper (the generated method
- * calls the unmanaged code in func)
+/**
+ * mono_marshal_get_icall_wrapper:
+ * Generates IL code for the icall wrapper. The generated method
+ * calls the unmanaged code in \p func.
  */
 MonoMethod *
 mono_marshal_get_icall_wrapper (MonoMethodSignature *sig, const char *name, gconstpointer func, gboolean check_exceptions)
@@ -7818,11 +7831,11 @@ mono_marshal_emit_native_wrapper (MonoImage *image, MonoMethodBuilder *mb, MonoM
 
 /**
  * mono_marshal_get_native_wrapper:
- * \param method The MonoMethod to wrap.
+ * \param method The \c MonoMethod to wrap.
  * \param check_exceptions Whenever to check for pending exceptions
  *
- * generates IL code for the pinvoke wrapper (the generated method
- * calls the unmanaged code in piinfo->addr)
+ * Generates IL code for the pinvoke wrapper. The generated method
+ * calls the unmanaged code in \c piinfo->addr.
  */
 MonoMethod *
 mono_marshal_get_native_wrapper (MonoMethod *method, gboolean check_exceptions, gboolean aot)
@@ -8742,9 +8755,10 @@ mono_marshal_set_callconv_from_modopt (MonoMethod *method, MonoMethodSignature *
        }
 }
 
-/*
- * generates IL code to call managed methods from unmanaged code 
- * If target_handle==0, the wrapper info will be a WrapperInfo structure.
+/**
+ * mono_marshal_get_managed_wrapper:
+ * Generates IL code to call managed methods from unmanaged code 
+ * If \p target_handle is \c 0, the wrapper info will be a \c WrapperInfo structure.
  */
 MonoMethod *
 mono_marshal_get_managed_wrapper (MonoMethod *method, MonoClass *delegate_klass, uint32_t target_handle, MonoError *error)
@@ -9063,8 +9077,9 @@ generate_check_cache (int obj_arg_position, int class_arg_position, int cache_ar
 
 #endif /* DISABLE_JIT */
 
-/*
- * This does the equivalent of mono_object_castclass_with_cache.
+/**
+ * mono_marshal_get_castclass_with_cache:
+ * This does the equivalent of \c mono_object_castclass_with_cache.
  */
 MonoMethod *
 mono_marshal_get_castclass_with_cache (void)
@@ -9146,8 +9161,9 @@ mono_marshal_isinst_with_cache (MonoObject *obj, MonoClass *klass, uintptr_t *ca
        return isinst;
 }
 
-/*
- * This does the equivalent of mono_object_isinst_with_cache.
+/**
+ * mono_marshal_get_isinst_with_cache:
+ * This does the equivalent of \c mono_object_isinst_with_cache.
  */
 MonoMethod *
 mono_marshal_get_isinst_with_cache (void)
@@ -9212,7 +9228,7 @@ mono_marshal_get_isinst_with_cache (void)
  * mono_marshal_get_struct_to_ptr:
  * \param klass \c MonoClass
  *
- * generates IL code for StructureToPtr (object structure, IntPtr ptr, bool fDeleteOld)
+ * Generates IL code for <code>StructureToPtr (object structure, IntPtr ptr, bool fDeleteOld)</code>
  */
 MonoMethod *
 mono_marshal_get_struct_to_ptr (MonoClass *klass)
@@ -9285,8 +9301,7 @@ mono_marshal_get_struct_to_ptr (MonoClass *klass)
 /**
  * mono_marshal_get_ptr_to_struct:
  * \param klass \c MonoClass
- *
- * generates IL code for PtrToStructure (IntPtr src, object structure)
+ * Generates IL code for <code>PtrToStructure (IntPtr src, object structure)</code>
  */
 MonoMethod *
 mono_marshal_get_ptr_to_struct (MonoClass *klass)
@@ -9405,9 +9420,10 @@ mono_marshal_get_synchronized_inner_wrapper (MonoMethod *method)
        return res;
 }
 
-/*
- * generates IL code for the synchronized wrapper: the generated method
- * calls METHOD while locking 'this' or the parent type.
+/**
+ * mono_marshal_get_synchronized_wrapper:
+ * Generates IL code for the synchronized wrapper: the generated method
+ * calls \p method while locking \c this or the parent type.
  */
 MonoMethod *
 mono_marshal_get_synchronized_wrapper (MonoMethod *method)
@@ -9598,8 +9614,9 @@ mono_marshal_get_synchronized_wrapper (MonoMethod *method)
 }
 
 
-/*
- * the returned method calls 'method' unboxing the this argument
+/**
+ * mono_marshal_get_unbox_wrapper:
+ * The returned method calls \p method unboxing the \c this argument.
  */
 MonoMethod *
 mono_marshal_get_unbox_wrapper (MonoMethod *method)
@@ -10160,6 +10177,9 @@ mono_marshal_get_virtual_stelemref_wrappers (int *nwrappers)
        return res;
 }
 
+/**
+ * mono_marshal_get_stelemref:
+ */
 MonoMethod*
 mono_marshal_get_stelemref (void)
 {
@@ -10654,6 +10674,9 @@ mono_marshal_alloc_co_task_mem (size_t size)
 }
 #endif
 
+/**
+ * mono_marshal_alloc:
+ */
 void*
 mono_marshal_alloc (gulong size, MonoError *error)
 {
@@ -10691,12 +10714,18 @@ mono_marshal_free_co_task_mem (void *ptr)
 }
 #endif
 
+/**
+ * mono_marshal_free:
+ */
 void
 mono_marshal_free (gpointer ptr)
 {
        mono_marshal_free_co_task_mem (ptr);
 }
 
+/**
+ * mono_marshal_free_array:
+ */
 void
 mono_marshal_free_array (gpointer *ptr, int size) 
 {
@@ -10739,7 +10768,7 @@ mono_marshal_string_to_utf16_copy (MonoString *s)
  * mono_marshal_set_last_error:
  *
  * This function is invoked to set the last error value from a P/Invoke call
- * which has SetLastError set.
+ * which has \c SetLastError set.
  */
 void
 mono_marshal_set_last_error (void)
@@ -11350,9 +11379,9 @@ mono_marshal_is_loading_type_info (MonoClass *klass)
 /**
  * mono_marshal_load_type_info:
  *
- *  Initialize klass::marshal_info using information from metadata. This function can
+ * Initialize \c klass::marshal_info using information from metadata. This function can
  * recursively call itself, and the caller is responsible to avoid that by calling 
- * mono_marshal_is_loading_type_info () beforehand.
+ * \c mono_marshal_is_loading_type_info beforehand.
  *
  * LOCKING: Acquires the loader lock.
  */
@@ -11624,6 +11653,9 @@ mono_type_native_stack_size (MonoType *t, guint32 *align)
        return 0;
 }
 
+/**
+ * mono_marshal_type_size:
+ */
 gint32
 mono_marshal_type_size (MonoType *type, MonoMarshalSpec *mspec, guint32 *align,
                        gboolean as_field, gboolean unicode)
@@ -11719,7 +11751,10 @@ mono_marshal_type_size (MonoType *type, MonoMarshalSpec *mspec, guint32 *align,
        return 0;
 }
 
-/* This is a JIT icall, it sets the pending exception and return NULL on error */
+/**
+ * mono_marshal_asany:
+ * This is a JIT icall, it sets the pending exception and returns NULL on error.
+ */
 gpointer
 mono_marshal_asany (MonoObject *o, MonoMarshalNative string_encoding, int param_attrs)
 {
@@ -11804,7 +11839,10 @@ mono_marshal_asany (MonoObject *o, MonoMarshalNative string_encoding, int param_
        return NULL;
 }
 
-/* This is a JIT icall, it sets the pending exception */
+/**
+ * mono_marshal_free_asany:
+ * This is a JIT icall, it sets the pending exception
+ */
 void
 mono_marshal_free_asany (MonoObject *o, gpointer ptr, MonoMarshalNative string_encoding, int param_attrs)
 {
index c58c94ea69ee0bbb15d93113a71be6e2cf9d2726..aee1b27ca833f4bf7646a6627711920bfcb09de8 100644 (file)
@@ -435,6 +435,9 @@ fail:
 } 
 
 
+/**
+ * mono_marshal_get_remoting_invoke:
+ */
 MonoMethod *
 mono_marshal_get_remoting_invoke (MonoMethod *method)
 {
@@ -908,7 +911,8 @@ mono_marshal_get_xappdomain_dispatch (MonoMethod *method, int *marshal_types, in
        return res;
 }
 
-/* mono_marshal_get_xappdomain_invoke ()
+/**
+ * mono_marshal_get_xappdomain_invoke:
  * Generates a fast remoting wrapper for cross app domain calls.
  */
 MonoMethod *
@@ -1238,6 +1242,9 @@ mono_marshal_get_xappdomain_invoke (MonoMethod *method)
        return res;
 }
 
+/**
+ * mono_marshal_get_remoting_invoke_for_target:
+ */
 MonoMethod *
 mono_marshal_get_remoting_invoke_for_target (MonoMethod *method, MonoRemotingTarget target_type)
 {
@@ -1270,6 +1277,9 @@ mono_marshal_load_remoting_wrapper (MonoRealProxy *rp, MonoMethod *method)
        return compiled_ptr;
 }
 
+/**
+ * mono_marshal_get_remoting_invoke_with_check:
+ */
 MonoMethod *
 mono_marshal_get_remoting_invoke_with_check (MonoMethod *method)
 {
@@ -1331,13 +1341,14 @@ mono_marshal_get_remoting_invoke_with_check (MonoMethod *method)
        return res;
 }
 
-/*
+/**
  * mono_marshal_get_ldfld_wrapper:
- * @type: the type of the field
+ * \param type the type of the field
  *
  * This method generates a function which can be use to load a field with type
- * @type from an object. The generated function has the following signature:
- * <@type> ldfld_wrapper (MonoObject *this_obj, MonoClass *klass, MonoClassField *field, int offset)
+ * \p type from an object. The generated function has the following signature:
+ *
+ * <code><i>type</i> ldfld_wrapper (MonoObject *this_obj, MonoClass *klass, MonoClassField *field, int offset)</code>
  */
 MonoMethod *
 mono_marshal_get_ldfld_wrapper (MonoType *type)
@@ -1625,13 +1636,14 @@ mono_marshal_get_ldflda_wrapper (MonoType *type)
 }
 
 
-/*
+/**
  * mono_marshal_get_stfld_wrapper:
- * @type: the type of the field
+ * \param type the type of the field
  *
  * This method generates a function which can be use to store a field with type
- * @type. The generated function has the following signature:
- * void stfld_wrapper (MonoObject *this_obj, MonoClass *klass, MonoClassField *field, int offset, <@type> val)
+ * \p type. The generated function has the following signature:
+ *
+ * <code>void stfld_wrapper (MonoObject *this_obj, MonoClass *klass, MonoClassField *field, int offset, <i>type</i> val)</code>
  */
 MonoMethod *
 mono_marshal_get_stfld_wrapper (MonoType *type)
@@ -1771,6 +1783,9 @@ mono_marshal_get_stfld_wrapper (MonoType *type)
        return res;
 }
 
+/**
+ * mono_marshal_get_proxy_cancast:
+ */
 MonoMethod *
 mono_marshal_get_proxy_cancast (MonoClass *klass)
 {
index a60fdb35f25f9224b3d3a784fa11e75b670fd5b3..f2958e964be0ddb76c22b4ff4ebd7574d827c121 100644 (file)
@@ -526,12 +526,18 @@ sgen_client_run_finalize (MonoObject *obj)
        mono_gc_run_finalize (obj, NULL);
 }
 
+/**
+ * mono_gc_invoke_finalizers:
+ */
 int
 mono_gc_invoke_finalizers (void)
 {
        return sgen_gc_invoke_finalizers ();
 }
 
+/**
+ * mono_gc_pending_finalizers:
+ */
 MonoBoolean
 mono_gc_pending_finalizers (void)
 {
@@ -984,6 +990,9 @@ mono_gc_alloc_mature (MonoVTable *vtable, size_t size)
        return obj;
 }
 
+/**
+ * mono_gc_alloc_fixed:
+ */
 void*
 mono_gc_alloc_fixed (size_t size, MonoGCDescriptor descr, MonoGCRootSource source, const char *msg)
 {
@@ -998,6 +1007,9 @@ mono_gc_alloc_fixed (size_t size, MonoGCDescriptor descr, MonoGCRootSource sourc
        return res;
 }
 
+/**
+ * mono_gc_free_fixed:
+ */
 void
 mono_gc_free_fixed (void* addr)
 {
@@ -2295,12 +2307,18 @@ sgen_thread_detach (SgenThreadInfo *p)
                mono_thread_detach_internal (mono_thread_internal_current ());
 }
 
+/**
+ * mono_gc_register_thread:
+ */
 gboolean
 mono_gc_register_thread (void *baseptr)
 {
        return mono_thread_info_attach (baseptr) != NULL;
 }
 
+/**
+ * mono_gc_is_gc_thread:
+ */
 gboolean
 mono_gc_is_gc_thread (void)
 {
@@ -2972,6 +2990,9 @@ sgen_client_describe_invalid_pointer (GCObject *ptr)
 
 static gboolean gc_inited;
 
+/**
+ * mono_gc_base_init:
+ */
 void
 mono_gc_base_init (void)
 {
index 42575b795077d6c8a8f761a8196253ef265dfdf9..9a160744b65253a0511fdd88e374ea097516a9dd 100644 (file)
@@ -263,6 +263,9 @@ mono_gc_get_bitmap_for_descr (SgenDescriptor descr, int *numbits)
        }
 }
 
+/**
+ * mono_gc_make_descr_from_bitmap:
+ */
 SgenDescriptor
 mono_gc_make_descr_from_bitmap (gsize *bitmap, int numbits)
 {