Axis2/C API Documentation

Presented below is a summary on improvements to API documentation. Please make sure that you obey the documenting conventions before proceeding with modifications to headers that have been marked finalized.

Documenting Convention

Below is the convention that should be followed. This is enforced to make sure that your comments are doxygen compatible. The conventions are enforced only for headers, and therefore does not affect source files.

File Names

Adding a file name MUST be done inside a file block starting with @{, as described in the Adding a file to module section below.

    /** @file <file_name> */

Ex:-

    /** @file axis2_msg_ctx.h */

Groups

Grouping of headers is not an easy task. Each header will belong to a module and each module will belong to the base.

Ex:-

    /**
      * @defgroup axis2_addr WS-Addressing
      * @ingroup axis2
      * @{
      * @}
      */

    /**
      * @defgroup axis2_addr_consts WS-Addressing related constants
      * @ingroup axis2_addr
      * @{
      */

However, the addition of a module to the base group MUST BE DONE ONLY ONCE. Therefore the portion,

    /**
      * @defgroup axis2_addr WS-Addressing
      * @ingroup axis2
      * @{
      * @}
      */

must NOT appear any where else.

Adding a module to base

    /**
      * @defgroup <module_name> <brief>
      * @ingroup axis2
      * @{
      * @}
      */

Adding a file to module

    /**
      * @defgroup <file_name> <brief>
      * @ingroup <module_name>
      * <expanded description>
      * @{
      */

Defines/Type Definitions

    /** <description> */

Methods

Documenting of methods is quite an easy task, which is mostly forgotten by many developers. You will have to add a brief description, followed by documentation of formal parameters using the @param directive, and finally documenting the return value using the @return directive.

    /**
     * <description>
     * @param <param_name> <description>
     * @param <param_name> <description>
     .
     .
     .

     * @return <description>
     */

Please make sure to document parameters in the order that they appear.

Ex:-

    /**
     * Sets a property with the given key.
     * @param ctx pointer to context struct
     * @param env pointer to environment struct
     * @param key key string to store the property with
     * @param value pointer to property to be stored, context assumes the 
     * ownership of the property
     * @param persistent persist ency status, AXIS2_TRUE if the value is to 
     * be stored in the resistant store, AXIS2_FALSE if it is to be stored 
     * in the non-persistent store
     * @return AXIS2_SUCCESS on success, else AXIS2_FAILURE
     */
    AXIS2_EXTERN axis2_status_t AXIS2_CALL
    axis2_ctx_set_property(
        struct axis2_ctx *ctx,
        const axutil_env_t * env,
        const axis2_char_t * key,
        axutil_property_t * value);

Common Mistakes to be avoided
  1. Using @returns instead of @return
  2. Documenting params in wrong order
  3. Misspelling or not including param name
  4. Forgetting to document params
  5. Unwanted parameters (due to a careless copy-paste)

Global Variables

TODO: need to agree on a convention.

Other

To mark the end of a file, you must add this at the bottom.

    /** @} */

Adding a See Also, to promote further reference is fairly easy

    /** @sa <file_name> */

Referring to a sub type inside a main type, main::sub is possible as,

    /** <main_type>#<sub_type> */

Adding newlines must be done on separate line, to improve readability

    /** \n */

Finalized Headers

Below is a list of headers finalized along with the respective path.

include

Name

Module

Name of assignee

Completed

Has Module Def

axis2_msg_ctx.h

axis2_context

Senaka

Yes

No

axis2_op_ctx.h

axis2_context

Senaka

Yes

No

axis2_ctx.h

axis2_context

Senaka

Yes

Yes

axis2_svc_ctx.h

axis2_context

Senaka

Yes

No

axis2_conf_ctx.h

axis2_context

Senaka

Yes

No

axis2_svc_grp_ctx.h

axis2_context

Senaka

Yes

No

axis2_svc_name.h

axis2_addr

Senaka

Yes

No

axis2_endpoint_ref.h

axis2_addr

Senaka

Yes

No

axis2_relates_to.h

axis2_addr

Senaka

Yes

No

axis2_msg_info_headers.h

axis2_addr

Senaka

Yes

No

axis2_any_content_type.h

axis2_addr

Senaka

Yes

No

axis2_addr.h

axis2_addr

Senaka

Yes

Yes

axis2_addr_mod.h

axis2_mod_addr

Senaka

Yes

Yes

axis2_desc.h

axis2_desc

Senaka

Yes

No

axis2_description.h

axis2_desc

Senaka

Yes

Yes

axis2_flow.h

axis2_desc

Senaka

Yes

No

axis2_module.h

axis2_desc

Senaka

Yes

No

axis2_msg.h

axis2_desc

Senaka

Yes

No

axis2_flow_container.h

axis2_desc

Senaka

Yes

No

axis2_handler_desc.h

axis2_desc

Senaka

Yes

No

axis2_module_desc.h

axis2_desc

Senaka

Yes

No

axiom/include

guththila/include

neethi/include

util/include

Conflicts and Other Errors

Other important notes