lib/doc.c

   1 /*
   2  * lib/doc.c            Documentation Purpose
   3  *
   4  *      This library is free software; you can redistribute it and/or
   5  *      modify it under the terms of the GNU Lesser General Public
   6  *      License as published by the Free Software Foundation version 2.1
   7  *      of the License.
   8  *
   9  * Copyright (c) 2003-2006 Thomas Graf <tgraf@suug.ch>
  10  */
  11
  12 /**
  13  * @mainpage
  14  *
  15  * @section remarks Remarks
  16  *
  17  * @subsection cache_alloc Allocation of Caches
  18  *
  19  * Almost all subsystem provide a function to allocate a new cache
  20  * of some form. The function usually looks like this:
  21  * @code
  22  * struct nl_cache *<object name>_alloc_cache(struct nl_handle *handle)
  23  * @endcode
  24  *
  25  * These functions allocate a new cache for the own object type,
  26  * initializes it properly and updates it to represent the current
  27  * state of their master, e.g. a link cache would include all
  28  * links currently configured in the kernel.
  29  *
  30  * Some of the allocation functions may take additional arguments
  31  * to further specify what will be part of the cache.
  32  *
  33  * All such functions return a newly allocated cache or NULL
  34  * in case of an error.
  35  *
  36  * @subsection addr Setting of Addresses
  37  * @code
  38  * int <object name>_set_addr(struct nl_object *, struct nl_addr *)
  39  * @endcode
  40  *
  41  * All attribute functions avaiable for assigning addresses to objects
  42  * take a struct nl_addr argument. The provided address object is
  43  * validated against the address family of the object if known already.
  44  * The assignment fails if the address families mismatch. In case the
  45  * address family has not been specified yet, the address family of
  46  * the new address is elected to be the new requirement.
  47  *
  48  * The function will acquire a new reference on the address object
  49  * before assignment, the caller is NOT responsible for this.
  50  *
  51  * All functions return 0 on success or a negative error code.
  52  *
  53  * @subsection flags Flags to Character StringTranslations
  54  * All functions converting a set of flags to a character string follow
  55  * the same principles, therefore, the following information applies
  56  * to all functions convertings flags to a character string and vice versa.
  57  *
  58  * @subsubsection flags2str Flags to Character String
  59  * @code
  60  * char *<object name>_flags2str(int flags, char *buf, size_t len)
  61  * @endcode
  62  * @arg flags           Flags.
  63  * @arg buf             Destination buffer.
  64  * @arg len             Buffer length.
  65  *
  66  * Converts the specified flags to a character string separated by
  67  * commas and stores it in the specified destination buffer.
  68  *
  69  * @return The destination buffer
  70  *
  71  * @subsubsection str2flags Character String to Flags
  72  * @code
  73  * int <object name>_str2flags(const char *name)
  74  * @endcode
  75  * @arg name            Name of flag.
  76  *
  77  * Converts the provided character string specifying a flag
  78  * to the corresponding numeric value.
  79  *
  80  * @return Link flag or a negative value if none was found.
  81  *
  82  * @subsubsection type2str Type to Character String
  83  * @code
  84  * char *<object name>_<type>2str(int type, char *buf, size_t len)
  85  * @endcode
  86  * @arg type            Type as numeric value
  87  * @arg buf             Destination buffer.
  88  * @arg len             Buffer length.
  89  *
  90  * Converts an identifier (type) to a character string and stores
  91  * it in the specified destination buffer.
  92  *
  93  * @return The destination buffer or the type encoded in hexidecimal
  94  *         form if the identifier is unknown.
  95  *
  96  * @subsubsection str2type Character String to Type
  97  * @code
  98  * int <object name>_str2<type>(const char *name)
  99  * @endcode
 100  * @arg name            Name of identifier (type).
 101  *
 102  * Converts the provided character string specifying a identifier
 103  * to the corresponding numeric value.
 104  *
 105  * @return Identifier as numeric value or a negative value if none was found.
 106  */