Fork us on GitHub Follow us on Facebook Follow us on Twitter

Changeset 8375d0eb in mainline


Ignore:
Timestamp:
2012-06-08T07:02:55Z (8 years ago)
Author:
Sean Bartell <wingedtachikoma@…>
Branches:
master
Children:
8b36bf2
Parents:
5c925ce
Message:

Bithenge: add Doxygen comments

Location:
uspace/app/bithenge
Files:
8 edited

Legend:

Unmodified
Added
Removed
  • uspace/app/bithenge/blob.c

    r5c925ce r8375d0eb  
    226226};
    227227
    228 /** Create a blob from data. Unlike with @a
     228/** Create a blob node from data. Unlike with @a
    229229 * bithenge_blob_t::bithenge_new_blob_from_buffer, the data is copied into a
    230230 * new buffer and the original data can be changed after this call. The blob
    231  * must be freed with @a bithenge_blob_t::bithenge_blob_destroy after it is
     231 * must be freed with @a bithenge_node_t::bithenge_node_destroy after it is
    232232 * used.
    233233 * @memberof bithenge_blob_t
    234  * @param[out] out Stores the created blob.
     234 * @param[out] out Stores the created blob node.
    235235 * @param[in] data The data.
    236236 * @param len The length of the data.
     
    264264}
    265265
    266 /** Create a blob from a buffer. The buffer must exist as long as the blob
    267  * does. The blob must be freed with @a bithenge_blob_t::bithenge_blob_destroy
     266/** Create a blob node from a buffer. The buffer must exist as long as the blob
     267 * does. The blob must be freed with @a bithenge_node_t::bithenge_node_destroy
    268268 * after it is used.
    269269 * @memberof bithenge_blob_t
    270  * @param[out] out Stores the created blob.
     270 * @param[out] out Stores the created blob node.
    271271 * @param[in] buffer The buffer, which must not be changed until the blob is
    272272 * destroyed.
  • uspace/app/bithenge/blob.h

    r5c925ce r8375d0eb  
    4141#include "tree.h"
    4242
    43 /** A blob of raw binary data. */
     43/** A blob of raw binary data.
     44 * @implements bithenge_node_t */
    4445typedef struct {
    4546        /** @privatesection */
     
    5556        int (*read)(bithenge_blob_t *blob, aoff64_t offset, char *buffer,
    5657            aoff64_t *size);
    57         /** @copydoc bithenge_blob_t::bithenge_blob_destroy */
     58        /** Destroy the blob.
     59         * @param blob The blob.
     60         * @return EOK on success or an error code from errno.h. */
    5861        int (*destroy)(bithenge_blob_t *blob);
    5962} bithenge_random_access_blob_ops_t;
     
    148151}
    149152
     153/** Cast a blob node to a generic node.
     154 * @memberof bithenge_blob_t
     155 * @param blob The blob to cast.
     156 * @return The blob node as a generic node. */
    150157static inline bithenge_node_t *bithenge_blob_as_node(bithenge_blob_t *blob)
    151158{
     
    153160}
    154161
     162/** Cast a generic node to a blob node.
     163 * @memberof bithenge_blob_t
     164 * @param node The node to cast, which must be a blob node.
     165 * @return The generic node as a blob node. */
    155166static inline bithenge_blob_t *bithenge_node_as_blob(bithenge_node_t *node)
    156167{
     168        assert(node->type == BITHENGE_NODE_BLOB);
    157169        return (bithenge_blob_t *)node;
    158170}
  • uspace/app/bithenge/block.c

    r5c925ce r8375d0eb  
    9393
    9494/** Create a blob for a block device. The blob must be freed with
    95  * @a bithenge_blob_t::bithenge_blob_destroy after it is used.
     95 * @a bithenge_node_t::bithenge_node_destroy after it is used.
    9696 * @param[out] out Stores the created blob.
    9797 * @param service_id The service ID of the block device.
  • uspace/app/bithenge/file.c

    r5c925ce r8375d0eb  
    133133
    134134/** Create a blob for a file. The blob must be freed with @a
    135  * bithenge_blob_t::bithenge_blob_destroy after it is used.
     135 * bithenge_node_t::bithenge_node_destroy after it is used.
    136136 * @param[out] out Stores the created blob.
    137137 * @param filename The name of the file.
     
    149149
    150150/** Create a blob for a file descriptor. The blob must be freed with @a
    151  * bithenge_blob_t::bithenge_blob_destroy after it is used.
     151 * bithenge_node_t::bithenge_node_destroy after it is used.
    152152 * @param[out] out Stores the created blob.
    153153 * @param fd The file descriptor.
     
    159159
    160160/** Create a blob for a file pointer. The blob must be freed with @a
    161  * bithenge_blob_t::bithenge_blob_destroy after it is used.
     161 * bithenge_node_t::bithenge_node_destroy after it is used.
    162162 * @param[out] out Stores the created blob.
    163163 * @param file The file pointer.
  • uspace/app/bithenge/print.c

    r5c925ce r8375d0eb  
    141141}
    142142
     143/** Print a tree as text.
     144 * @param type The format to use.
     145 * @param tree The root node of the tree to print.
     146 * @return EOK on success or an error code from errno.h. */
    143147int bithenge_print_node(bithenge_print_type_t type, bithenge_node_t *tree)
    144148{
    145149        switch (bithenge_node_type(tree)) {
    146         case BITHENGE_NODE_NONE:
    147                 return EINVAL;
    148150        case BITHENGE_NODE_INTERNAL:
    149151                return print_internal(type, tree);
     
    159161        return ENOTSUP;
    160162}
     163
     164/** @}
     165 */
  • uspace/app/bithenge/print.h

    r5c925ce r8375d0eb  
    4040#include "tree.h"
    4141
     42/** Specifies the format to be used when printing. */
    4243typedef enum {
     44        /** Print a Python value. Note that internal nodes will be represented
     45         * as unordered dictionaries. */
    4346        BITHENGE_PRINT_PYTHON,
     47        /** Print JSON. Due to the limitations of JSON, type information may be
     48         * lost. */
    4449        BITHENGE_PRINT_JSON,
    4550} bithenge_print_type_t;
  • uspace/app/bithenge/tree.c

    r5c925ce r8375d0eb  
    4747}
    4848
     49/** Destroy a node.
     50 * @memberof bithenge_node_t
     51 * @param node The node to destroy.
     52 * @return EOK on success or an error code from errno.h. */
    4953int bithenge_node_destroy(bithenge_node_t *node)
    5054{
     
    6165                return EOK; // the boolean nodes are allocated statically below
    6266        case BITHENGE_NODE_INTEGER: /* pass-through */
    63         case BITHENGE_NODE_NONE:
    6467                break;
    6568        }
     
    8184}
    8285
    83 static int simple_internal_node_for_each(bithenge_node_t *base, bithenge_for_each_func_t func, void *data)
     86static int simple_internal_node_for_each(bithenge_node_t *base,
     87    bithenge_for_each_func_t func, void *data)
    8488{
    8589        int rc;
     
    121125}
    122126
    123 int bithenge_new_simple_internal_node(bithenge_node_t **out, bithenge_node_t **nodes, bithenge_int_t len, bool needs_free)
     127/** Create an internal node from a set of keys and values. The node must be
     128 * freed with @a bithenge_node_t::bithenge_node_destroy after it is used, which
     129 * will also destroy all the key and value nodes.
     130 * @memberof bithenge_node_t
     131 * @param[out] out Stores the created internal node.
     132 * @param nodes The array of key-value pairs. Keys are stored at even indices
     133 * and values are stored at odd indices.
     134 * @param len The number of key-value pairs in the node array.
     135 * @param needs_free If true, when the internal node is destroyed it will free
     136 * the nodes array as well as destroying each node inside it.
     137 * @return EOK on success or an error code from errno.h. */
     138int bithenge_new_simple_internal_node(bithenge_node_t **out,
     139    bithenge_node_t **nodes, bithenge_int_t len, bool needs_free)
    124140{
    125141        assert(out);
     
    139155static bithenge_node_t true_node = { BITHENGE_NODE_BOOLEAN, .boolean_value = true };
    140156
     157/** Create a boolean node. The node must be freed with @a
     158 * bithenge_node_t::bithenge_node_destroy after it is used.
     159 * @memberof bithenge_node_t
     160 * @param[out] out Stores the created boolean node.
     161 * @param value The value for the node to hold.
     162 * @return EOK on success or an error code from errno.h. */
    141163int bithenge_new_boolean_node(bithenge_node_t **out, bool value)
    142164{
     
    146168}
    147169
     170/** Create an integer node. The node must be freed with @a
     171 * bithenge_node_t::bithenge_node_destroy after it is used.
     172 * @memberof bithenge_node_t
     173 * @param[out] out Stores the created integer node.
     174 * @param value The value for the node to hold.
     175 * @return EOK on success or an error code from errno.h. */
    148176int bithenge_new_integer_node(bithenge_node_t **out, bithenge_int_t value)
    149177{
     
    158186}
    159187
     188/** Create a string node. The node must be freed with @a
     189 * bithenge_node_t::bithenge_node_destroy after it is used.
     190 * @memberof bithenge_node_t
     191 * @param[out] out Stores the created string node.
     192 * @param value The value for the node to hold.
     193 * @param needs_free Whether the string should be freed when the node is
     194 * destroyed.
     195 * @return EOK on success or an error code from errno.h. */
    160196int bithenge_new_string_node(bithenge_node_t **out, const char *value, bool needs_free)
    161197{
     
    170206        return EOK;
    171207}
     208
     209/** @}
     210 */
  • uspace/app/bithenge/tree.h

    r5c925ce r8375d0eb  
    5151#endif
    5252
     53/** Indicates the type of a tree node. */
    5354typedef enum {
    54         BITHENGE_NODE_NONE,
    55         BITHENGE_NODE_INTERNAL,
     55        /** An internal node with labelled edges to other nodes. */
     56        BITHENGE_NODE_INTERNAL = 1,
     57        /** A leaf node holding a boolean value. */
    5658        BITHENGE_NODE_BOOLEAN,
     59        /** A leaf node holding an integer. */
    5760        BITHENGE_NODE_INTEGER,
     61        /** A leaf node holding a string. */
    5862        BITHENGE_NODE_STRING,
     63        /** A leaf node holding a binary blob. */
    5964        BITHENGE_NODE_BLOB,
    6065} bithenge_node_type_t;
    6166
    6267typedef struct bithenge_node_t {
     68        /** @privatesection */
    6369        bithenge_node_type_t type;
    6470        union {
     
    7480} bithenge_node_t;
    7581
     82/** A callback function used to iterate over a node's children.
     83 * @memberof bithenge_node_t
     84 * @param key The key.
     85 * @param value The value.
     86 * @param data Data provided to @a bithenge_node_t::bithenge_node_for_each.
     87 * @return EOK on success or an error code from errno.h. */
     88typedef int (*bithenge_for_each_func_t)(bithenge_node_t *key, bithenge_node_t *value, void *data);
     89
     90/** Operations providing access to an internal node. */
     91typedef struct bithenge_internal_node_ops_t {
     92        /** @copydoc bithenge_node_t::bithenge_node_for_each */
     93        int (*for_each)(bithenge_node_t *node, bithenge_for_each_func_t func, void *data);
     94        /** @copydoc bithenge_node_t::bithenge_node_destroy */
     95        int (*destroy)(bithenge_node_t *node);
     96} bithenge_internal_node_ops_t;
     97
     98/** Find the type of a node.
     99 * @memberof bithenge_node_t
     100 * @param node The node.
     101 * @return The type of the node. */
    76102static inline bithenge_node_type_t bithenge_node_type(const bithenge_node_t *node)
    77103{
     
    79105}
    80106
    81 typedef int (*bithenge_for_each_func_t)(bithenge_node_t *key, bithenge_node_t *value, void *data);
    82 
    83 typedef struct bithenge_internal_node_ops_t {
    84         int (*for_each)(bithenge_node_t *node, bithenge_for_each_func_t func, void *data);
    85         int (*destroy)(bithenge_node_t *node);
    86 } bithenge_internal_node_ops_t;
    87 
     107/** Iterate over a node's children.
     108 * @memberof bithenge_node_t
     109 * @param node The internal node to iterate over.
     110 * @param func The callback function.
     111 * @param data Data to provide to the callback function.
     112 * @return EOK on success or an error code from errno.h. */
    88113static inline int bithenge_node_for_each(bithenge_node_t *node, bithenge_for_each_func_t func, void *data)
    89114{
     
    92117}
    93118
     119/** Get the value of a boolean node.
     120 * @memberof bithenge_node_t
     121 * @param node The boolean node.
     122 * @return The node's value. */
    94123static inline bool bithenge_boolean_node_value(bithenge_node_t *node)
    95124{
     
    98127}
    99128
     129/** Get the value of an integer node.
     130 * @memberof bithenge_node_t
     131 * @param node The integer node.
     132 * @return The node's value. */
    100133static inline bithenge_int_t bithenge_integer_node_value(bithenge_node_t *node)
    101134{
     
    104137}
    105138
     139/** Get the value of an string node.
     140 * @memberof bithenge_node_t
     141 * @param node The string node.
     142 * @return The node's value. */
    106143static inline const char *bithenge_string_node_value(bithenge_node_t *node)
    107144{
     
    110147}
    111148
    112 int bithenge_new_simple_internal_node(bithenge_node_t **, bithenge_node_t **, bithenge_int_t, bool needs_free);
     149int bithenge_new_simple_internal_node(bithenge_node_t **, bithenge_node_t **,
     150    bithenge_int_t, bool needs_free);
    113151int bithenge_new_boolean_node(bithenge_node_t **, bool);
    114152int bithenge_new_integer_node(bithenge_node_t **, bithenge_int_t);
Note: See TracChangeset for help on using the changeset viewer.