Index: trunk/vm/include/component_manager.h =================================================================== --- trunk/vm/include/component_manager.h (revision 527072) +++ trunk/vm/include/component_manager.h (working copy) @@ -1,4 +1,4 @@ -/* +/** * Licensed to the Apache Software Foundation (ASF) under one or more * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. @@ -25,12 +25,12 @@ #endif /** - * If no component manager exist, initializes a component manager. - * Otherwise, increases a component manager reference count. + * Initializes a component manager if it does not exist. + * Otherwise, increases a component-manager reference count. * * This function is safe to call from multiple threads. * - * @param[out] p_cm - on return, points to a component manager + * @param[out] p_cm - on return, points to a component-manager * interface handle * * @return APR_SUCCESS if successful, or a non-zero error code. @@ -38,7 +38,7 @@ int CmAcquire(OpenComponentManagerHandle* p_cm); /** - * Decrement a reference counter and destroy a component manager if it + * Decrements a reference counter and destroys a component manager if it * becomes zero. The caller should ensure no cached handles will be used. * * This function is safe to call from multiple threads. @@ -48,9 +48,9 @@ int CmRelease(); /** - * Register a buitin component in a component manager. + * Registers a built-in component in a component manager. * - * @param init_func - initializer function which provides a default + * @param init_func - the initializer function providing a default * and private interfaces for the component * * This function is safe to call from multiple threads. @@ -60,15 +60,16 @@ int CmAddComponent(OpenComponentInitializer init_func); /** - * Load a dynamic library if not loaded, and register - * the component with a given initializer function - * in a component manager. + * Loads a dynamic library if it was not loaded, and registers + * the component with the given initializer function in a component manager. * * This function is safe to call from multiple threads. * - * @param path - path to DLL which contains a component - * @param initializer_function_name - a name of a function of OpenComponentInitializer - * type that registers a component in a component manager + * @param path - the path to DLL, which contains a component + * @param initializer_function_name - the function name of the + * OpenComponentInitializer type + * that registers a component in a component + * manager * * @return APR_SUCCESS if successful, or a non-zero error code. */ @@ -76,10 +77,10 @@ const char* initializer_function_name); /** - * Deallocate all instances of a given component, unregister a component in a - * component manager, and free all component resources using - * Free function. If the component is loaded from a dynamic - * library and no components are using the library, then unload + * De-allocates all instances of the given component, unregisters a component in a + * component manager, and frees all component resources using the + * Free function. If the component is loaded from a dynamic + * library and no components are using the library, then unloads * the dynamic library. * * This function is safe to call from multiple threads. Index: trunk/vm/include/open/compmgr.h =================================================================== --- trunk/vm/include/open/compmgr.h (revision 527072) +++ trunk/vm/include/open/compmgr.h (working copy) @@ -1,10 +1,10 @@ -/* +/** * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with + * contributor license agreements. See the NOTICE file distributed with * this work for additional information regarding copyright ownership. * The ASF licenses this file to You under the Apache License, Version 2.0 * (the "License"); you may not use this file except in compliance with - * the License. You may obtain a copy of the License at + * the License. You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * @@ -14,18 +14,18 @@ * See the License for the specific language governing permissions and * limitations under the License. */ -/** + +/** * @author Intel, Alexei Fedotov * @version $Revision: 1.1.2.2.4.3 $ */ /** * @file - * - * The file contains description of public component manager handles - * and interfaces for initialization and dynamic linking of VM components. + * Description of public component-manager handles and interfaces for + * initialization and dynamic linking of VM components. */ - + #ifndef _OPEN_COMPMGR_H #define _OPEN_COMPMGR_H @@ -37,25 +37,25 @@ #endif /** - * The _OpenInterface structure represents - * a virtual table of interface functions. + * The _OpenInterface structure represents a virtual table of + * interface functions. + * + * A real interface can contain more function pointers. + *
+ * void* func2;
+ * void* func3;
+ * 
*/ struct _OpenInterface { void* func1; - /* - * A real interface can contain more - * function pointers. - * - * void* func2; - * void* func3; - */ + }; /** * @name Handles - * Handles are opaque for an interface user. The user - * operates with handles by means of interface functions. + * Handles are opaque for an interface user. The user operates with handles + * by means of interface functions. */ /** @@ -65,79 +65,76 @@ typedef const struct _OpenInterface* OpenInterfaceHandle; /** - * Default component interface. Each component must - * provide implementation of the functions from this - * interface. + * The default component interface. Each component must provide implementation + * of the functions from this interface. */ struct _OpenComponent { - /** - * Returns a component name. - */ +/** Returns a component name.*/ const char* (*GetName) (); - /** - * Returns a component version which is numbers separated with dots. - * Implementors must check a major version number for compatibility. - */ +/** + * Returns a component version where numbers are separated with dots. + * Implementors must check the major version number for compatibility. + */ const char* (*GetVersion) (); - /** - * Returns human-readable description of the component. - */ +/** Returns the human-readable description of the component.*/ const char* (*GetDescription) (); - /** - * Returns the human-readable vendor string, e. g., - * name of the organization which provides this component. - */ +/** + * Returns the human-readable vendor string, for example, the name of the + * organization providing this component. + */ const char* (*GetVendor) (); - /** - * Queries optional properties. - * @param key property name - * @return a string, true/false for boolean properties - */ +/** + * Queries optional properties. + * + * @param key - the property name + * @return A string, TRUE/FALSE for boolean properties. + */ const char* (*GetProperty) (const char* key); - /** - * Exposes a NULL terminated list of component-specific - * interface names for the given component. - * - * This default component interface is not included. - * @return a pointer to an internal component manager structure, - * which should not be modified or freed. - */ +/** + * Exposes a NULL terminated list of component-specific interface + * names for the given component. + * + * This default component interface is not included. + * + * @return A pointer to an internal component-manager structure, which should + * not be modified or freed. + */ const char** (*ListInterfaceNames) (); - /** - * Exposes a component interface. - * @param[out] p_intf on return, points to an interface handle - * @param intf_name an interface name - * @return APR_SUCCESS if successful, otherwise a non-zero error code - */ +/** + * Exposes a component interface. + * + * @param[out] p_intf - on return, points to an interface handle + * @param intf_name - an interface name + * @return APR_SUCCESS if successful, otherwise a non-zero error code. + */ int (*GetInterface) (OpenInterfaceHandle* p_intf, const char* intf_name); - /** - * The call to this function frees all component resources. - * @return APR_SUCCESS if successful, otherwise a non-zero error code - */ +/** + * The call to this function frees all component resources. + * + * @return APR_SUCCESS if successful, otherwise a non-zero error code. + */ int (*Free) (); }; /** * @ingroup Handles - * The handle of the open component. + * The open component handle. */ typedef const struct _OpenComponent* OpenComponentHandle; -/** - * The generic component instance. - */ +/** The generic component instance.*/ struct _OpenInstance { OpenComponentHandle intf; }; /** * @ingroup Handles - * The handle of the open instance. + * The open instance handle. */ typedef const struct _OpenInstance* OpenInstanceHandle; @@ -146,24 +143,26 @@ * and dispose instances. */ struct _OpenInstanceAllocator { - /** - * The component provides a constructor-like method for instance - * initialization which is called by component manager when a - * new instance is created. - * - * @param[out] p_instance on return, points to handle of a new instance - * @param pool created by a component manager for a lifetime of - * the instance, the component could use the pool for allocation - * @return APR_SUCCESS if successful, otherwise a non-zero error code - */ +/** + * The component provides a constructor-like method for instance + * initialization which is called by a component manager when a + * new instance is created. + * + * @param[out] p_instance - on return, points to the new instance handle + * @param pool - the pool created by a component manager for a + * lifetime of the instance, the component can use + * the pool for allocation + * @return APR_SUCCESS if successful, otherwise a non-zero error code. + */ int (*CreateInstance) (OpenInstanceHandle* p_instance, apr_pool_t* pool); - /** - * Free memory and other resources for a given instance. - * @param instance a handle of an instance to free - * @return APR_SUCCESS if successful, otherwise a non-zero error code - */ +/** + * Free memory and other resources for the given instance. + * + * @param instance - a handle of an instance to free + * @return APR_SUCCESS if successful, otherwise a non-zero error code. + */ int (*FreeInstance) (OpenInstanceHandle instance); }; /** @@ -173,7 +172,7 @@ typedef const struct _OpenInstanceAllocator* OpenInstanceAllocatorHandle; /** - * The virtual table which contains public component manager + * The virtual table containing the public component-manager * interface. The interface allows accessing components by name * and operating with component instances. * @@ -182,50 +181,53 @@ struct _OpenComponentManager { - /** - * Get a default interface of a registered component by name. - * @param[out] p_component on return, points to - * a handle of default component interface - * @param name a component name - * @return APR_SUCCESS if successful, otherwise a non-zero error code - */ +/** + * Gets a default interface of a registered component by name. + * + * @param[out] p_component - on return, points to a handle of default component + * interface + * @param name - the component name + * @return APR_SUCCESS if successful, otherwise a non-zero error code. + */ int (*GetComponent) (OpenComponentHandle* p_component, const char* name); - /** - * Create a new component instance and register it in - * a component manager. - * @param[out] p_instance on return, points to a handle of a newly - * created instance - * @param name a name of interface - * @return APR_SUCCESS if successful, otherwise a non-zero error code - */ +/** + * Creates a new component instance and registers it in a component manager. + * + * @param[out] p_instance - on return, points to a handle of a newly + * created instance + * @param name - the interface name + * @return APR_SUCCESS if successful, otherwise a non-zero error code. + */ int (*CreateInstance) (OpenInstanceHandle* p_instance, const char* name); - /** - * Unregister the instance in a component manager, - * free memory and other resources held by the instance. - * @param instance a handle to the instance to Free - * @return APR_SUCCESS if successful, otherwise a non-zero error code - */ +/** + * Unregisters the instance in a component manager, free memory and other + * resources held by the instance. + * + * @param instance - a handle to the instance to Free + * @return APR_SUCCESS if successful, otherwise a non-zero error code. + */ int (*FreeInstance) (OpenInstanceHandle instance); }; /** * @ingroup Handles - * The handle of the component manager interface. + * The handle of the component-manager interface. */ typedef const struct _OpenComponentManager* OpenComponentManagerHandle; /** * The generic component initialization function type. - * @param[out] p_component on return, points to a handle of a default - * component interface - * @param[out] p_allocator on return, points to a handle of a private - * instance allocation interface - * @param pool a memory pool with the component lifetime - * @return APR_SUCCESS if successful, otherwise a non-zero error code + * + * @param[out] p_component - on return, points to a handle of a default + * component interface + * @param[out] p_allocator - on return, points to a handle of a private + * instance allocation interface + * @param pool - the memory pool with the component lifetime + * @return APR_SUCCESS if successful, otherwise a non-zero error code. */ typedef int (*OpenComponentInitializer) (OpenComponentHandle* p_component,