Changeset 0784869 in mainline


Ignore:
Timestamp:
2012-08-20T17:32:00Z (12 years ago)
Author:
Sean Bartell <wingedtachikoma@…>
Branches:
lfn, master, serial, ticket/834-toolchain-update, topic/msim-upgrade, topic/simplify-dev-export
Children:
1f136a27
Parents:
1a3b953
Message:

Bithenge: improve Doxygen documentation

Location:
uspace/lib/bithenge
Files:
10 edited

Legend:

Unmodified
Added
Removed

  • uspace/lib/bithenge/blob.h

    r1a3b953 r0784869  
    233233}
    234234
     235/** @memberof bithenge_blob_t */
    235236int bithenge_init_random_access_blob(bithenge_blob_t *,
    236237    const bithenge_random_access_blob_ops_t *);
     238/** @memberof bithenge_sequential_blob_t */
    237239int bithenge_init_sequential_blob(bithenge_sequential_blob_t *,
    238240    const bithenge_sequential_blob_ops_t *);
     241/** @memberof bithenge_blob_t */
    239242int bithenge_new_blob_from_data(bithenge_node_t **, const void *, size_t);
     243/** @memberof bithenge_blob_t */
    240244int bithenge_new_blob_from_buffer(bithenge_node_t **, const void *, size_t,
    241245    bool);
    … …  
    243247int bithenge_new_subblob(bithenge_node_t **, bithenge_blob_t *, aoff64_t,
    244248    aoff64_t);
     249/** @memberof bithenge_blob_t */
    245250int bithenge_blob_equal(bool *, bithenge_blob_t *, bithenge_blob_t *);
    246251

  • uspace/lib/bithenge/expression.c

    r1a3b953 r0784869  
    530530};
    531531
     532/** Create an expression that gets a member from one of the current nodes being
     533 * created. It searches from the current scope outwards, stopping at barrier
     534 * scopes.
     535 * @param[out] out Holds the new expression.
     536 * @param key The key to search for in nodes being created.
     537 * @return EOK on success or an error code from errno.h. */
    532538int bithenge_scope_member_expression(bithenge_expression_t **out,
    533539    bithenge_node_t *key)

  • uspace/lib/bithenge/expression.h

    r1a3b953 r0784869  
    9393}
    9494
     95/** The binary operators supported by @a bithenge_binary_expression(). */
    9596typedef enum {
    9697        BITHENGE_EXPRESSION_INVALID_BINARY_OP,

  • uspace/lib/bithenge/failure.c

    r1a3b953 r0784869  
    2727 */
    2828
     29/** @cond internal */
    2930/** @addtogroup bithenge
    3031 * @{
    … …  
    237238/** @}
    238239 */
     240/** @endcond */

  • uspace/lib/bithenge/failure.h

    r1a3b953 r0784869  
    2727 */
    2828
     29/** @cond internal */
    2930/** @addtogroup bithenge
    3031 * @{
    … …  
    7172/** @}
    7273 */
     74
     75/** @endcond */
     76

  • uspace/lib/bithenge/script.c

    r1a3b953 r0784869  
    4646#include "tree.h"
    4747
     48/** @cond internal */
     49#define BUFFER_SIZE 4096
     50/** @endcond */
     51
    4852/** Tokens with more characters than this may be read incorrectly. */
    49 #define MAX_TOKEN_SIZE 256
    50 #define BUFFER_SIZE 4096
    51 
    52 /** Single-character symbols are represented by the character itself. Every
     53static const int MAX_TOKEN_SIZE = 256;
     54
     55/** @cond internal
     56 * Single-character symbols are represented by the character itself. Every
    5357 * other token uses one of these values: */
    5458typedef enum {
    … …  
    8286        TOKEN_WHILE,
    8387} token_type_t;
     88/** @endcond */
    8489
    8590/** Singly-linked list of named transforms. */
    … …  
    438443/***************** Expressions                               *****************/
    439444
     445/** @cond internal */
    440446typedef enum {
    441447        PRECEDENCE_NONE,
    … …  
    446452        PRECEDENCE_MULTIPLY,
    447453} precedence_t;
     454/** @endcond */
    448455
    449456static bithenge_binary_op_t token_as_binary_operator(token_type_t token)

  • uspace/lib/bithenge/transform.c

    r1a3b953 r0784869  
    184184/** Create a transform scope. It must be dereferenced with @a
    185185 * bithenge_scope_dec_ref after it is used. Takes ownership of nothing.
     186 * @memberof bithenge_scope_t
    186187 * @param[out] out Holds the new scope.
    187188 * @param outer The outer scope, or NULL.
    … …  
    207208
    208209/** Dereference a transform scope.
    209  * @param self The scope to dereference. */
     210 * @memberof bithenge_scope_t
     211 * @param self The scope to dereference, or NULL. */
    210212void bithenge_scope_dec_ref(bithenge_scope_t *self)
    211213{
    … …  
    224226
    225227/** Get the outer scope of a scope, which may be NULL.
     228 * @memberof bithenge_scope_t
    226229 * @param self The scope to examine.
    227230 * @return The outer scope, which may be NULL. */
    … …  
    233236/** Get the error message stored in the scope, which may be NULL. The error
    234237 * message only exists as long as the scope does.
     238 * @memberof bithenge_scope_t
    235239 * @param scope The scope to get the error message from.
    236240 * @return The error message, or NULL. */
    … …  
    243247 * outermost scope, but if any scope already has an error message this error
    244248 * message is ignored.
     249 * @memberof bithenge_scope_t
    245250 * @param scope The scope.
    246251 * @param format The format string.
    … …  
    292297
    293298/** Get the current node being created, which may be NULL.
     299 * @memberof bithenge_scope_t
    294300 * @param scope The scope to get the current node from.
    295301 * @return The node being created, or NULL. */
    … …  
    302308
    303309/** Set the current node being created. Takes a reference to @a node.
     310 * @memberof bithenge_scope_t
    304311 * @param scope The scope to set the current node in.
    305312 * @param node The current node being created, or NULL. */
    … …  
    312319
    313320/** Get the current input node, which may be NULL.
     321 * @memberof bithenge_scope_t
    314322 * @param scope The scope to get the current input node from.
    315323 * @return The input node, or NULL. */
    … …  
    322330
    323331/** Set the current input node. Takes a reference to @a node.
     332 * @memberof bithenge_scope_t
    324333 * @param scope The scope to set the input node in.
    325334 * @param node The input node, or NULL. */
    … …  
    331340
    332341/** Set a scope as a barrier.
     342 * @memberof bithenge_scope_t
    333343 * @param self The scope to change. */
    334344void bithenge_scope_set_barrier(bithenge_scope_t *self)
    … …  
    339349/** Check whether a scope is a barrier, meaning that variable lookup stops at
    340350 * it.
     351 * @memberof bithenge_scope_t
    341352 * @param self The scope to check.
    342353 * @return Whether the scope is a barrier. */
    … …  
    349360 * bithenge_scope_set_param. This must not be called on a scope that already
    350361 * has parameters.
     362 * @memberof bithenge_scope_t
    351363 * @param scope The scope in which to allocate parameters.
    352364 * @param num_params The number of parameters to allocate.
    … …  
    363375}
    364376
    365 /** Set a parameter. Takes a reference to @a value. Note that range checking is
     377/** Set a parameter. Takes a reference to @a node. Note that range checking is
    366378 * not done in release builds.
     379 * @memberof bithenge_scope_t
    367380 * @param scope The scope in which to allocate parameters.
    368381 * @param i The index of the parameter to set.
    369  * @param value The value to store in the parameter.
     382 * @param node The value to store in the parameter.
    370383 * @return EOK on success or an error code from errno.h. */
    371384int bithenge_scope_set_param( bithenge_scope_t *scope, int i,
    … …  
    383396
    384397/** Get a parameter. Note that range checking is not done in release builds.
     398 * @memberof bithenge_scope_t
    385399 * @param scope The scope to get the parameter from.
    386400 * @param i The index of the parameter to set.
    … …  
    867881}
    868882
     883/** @cond internal */
    869884#define MAKE_UINT_TRANSFORM(NAME, TYPE, ENDIAN, PREFIX_LENGTH_FUNC)            \
    870885        static int NAME##_apply(bithenge_transform_t *self,                    \
    … …  
    906921MAKE_UINT_TRANSFORM(uint64le, uint64_t, uint64_t_le2host, prefix_length_8);
    907922MAKE_UINT_TRANSFORM(uint64be, uint64_t, uint64_t_be2host, prefix_length_8);
     923/** @endcond */
    908924
    909925

  • uspace/lib/bithenge/transform.h

    r1a3b953 r0784869  
    6262} bithenge_scope_t;
    6363
    64 static inline void bithenge_scope_inc_ref(bithenge_scope_t *self) {
     64/** Increment a scope's reference count.
     65 * @memberof bithenge_scope_t
     66 * @param self The scope to reference. */
     67static inline void bithenge_scope_inc_ref(bithenge_scope_t *self)
     68{
     69        assert(self);
    6570        self->refs++;
    6671}
    … …  
    117122/** A transform with a name. */
    118123typedef struct {
     124        /** The transform's name. */
    119125        const char *name;
     126        /** The transform. */
    120127        bithenge_transform_t *transform;
    121128} bithenge_named_transform_t;
    122129
     130/** Transform that decodes an 8-bit unsigned integer */
     131extern bithenge_transform_t bithenge_uint8_transform;
     132/** Transform that decodes a 16-bit little-endian unsigned integer */
     133extern bithenge_transform_t bithenge_uint16le_transform;
     134/** Transform that decodes a 16-bit big-endian unsigned integer */
     135extern bithenge_transform_t bithenge_uint16be_transform;
     136/** Transform that decodes a 32-bit little-endian unsigned integer */
     137extern bithenge_transform_t bithenge_uint32le_transform;
     138/** Transform that decodes a 32-bit big-endian unsigned integer */
     139extern bithenge_transform_t bithenge_uint32be_transform;
     140/** Transform that decodes a 64-bit little-endian unsigned integer */
     141extern bithenge_transform_t bithenge_uint64le_transform;
     142/** Transform that decodes a 64-bit big-endian unsigned integer */
     143extern bithenge_transform_t bithenge_uint64be_transform;
     144
     145/** @cond */
    123146extern bithenge_transform_t bithenge_ascii_transform;
    124147extern bithenge_transform_t bithenge_bit_transform;
    … …  
    128151extern bithenge_transform_t bithenge_known_length_transform;
    129152extern bithenge_transform_t bithenge_nonzero_boolean_transform;
    130 extern bithenge_transform_t bithenge_uint8_transform;
    131 extern bithenge_transform_t bithenge_uint16le_transform;
    132 extern bithenge_transform_t bithenge_uint16be_transform;
    133 extern bithenge_transform_t bithenge_uint32le_transform;
    134 extern bithenge_transform_t bithenge_uint32be_transform;
    135 extern bithenge_transform_t bithenge_uint64le_transform;
    136 extern bithenge_transform_t bithenge_uint64be_transform;
    137153extern bithenge_transform_t bithenge_uint_le_transform;
    138154extern bithenge_transform_t bithenge_uint_be_transform;
    139155extern bithenge_transform_t bithenge_zero_terminated_transform;
    140156extern bithenge_named_transform_t *bithenge_primitive_transforms;
    141 
     157/** @endcond */
     158
     159/** @memberof bithenge_transform_t */
    142160int bithenge_init_transform(bithenge_transform_t *,
    143161    const bithenge_transform_ops_t *, int);
     162/** @memberof bithenge_transform_t */
    144163int bithenge_transform_apply(bithenge_transform_t *, bithenge_scope_t *,
    145164    bithenge_node_t *, bithenge_node_t **);
     165/** @memberof bithenge_transform_t */
    146166int bithenge_transform_prefix_length(bithenge_transform_t *,
    147167    bithenge_scope_t *, bithenge_blob_t *, aoff64_t *);
     168/** @memberof bithenge_transform_t */
    148169int bithenge_transform_prefix_apply(bithenge_transform_t *, bithenge_scope_t *,
    149170    bithenge_blob_t *, bithenge_node_t **, aoff64_t *);
    … …  
    152173    bithenge_transform_t *);
    153174
     175/** @memberof bithenge_scope_t */
    154176int bithenge_scope_new(bithenge_scope_t **, bithenge_scope_t *);
     177/** @memberof bithenge_scope_t */
    155178void bithenge_scope_dec_ref(bithenge_scope_t *);
     179/** @memberof bithenge_scope_t */
    156180bithenge_scope_t *bithenge_scope_outer(bithenge_scope_t *);
     181/** @memberof bithenge_scope_t */
    157182const char *bithenge_scope_get_error(bithenge_scope_t *);
     183/** @memberof bithenge_scope_t */
    158184int bithenge_scope_error(bithenge_scope_t *, const char *, ...);
     185/** @memberof bithenge_scope_t */
    159186bithenge_node_t *bithenge_scope_get_current_node(bithenge_scope_t *);
     187/** @memberof bithenge_scope_t */
    160188void bithenge_scope_set_current_node(bithenge_scope_t *, bithenge_node_t *);
     189/** @memberof bithenge_scope_t */
    161190bithenge_node_t *bithenge_scope_in_node(bithenge_scope_t *);
     191/** @memberof bithenge_scope_t */
    162192void bithenge_scope_set_in_node(bithenge_scope_t *, bithenge_node_t *);
     193/** @memberof bithenge_scope_t */
    163194void bithenge_scope_set_barrier(bithenge_scope_t *);
     195/** @memberof bithenge_scope_t */
    164196bool bithenge_scope_is_barrier(bithenge_scope_t *);
     197/** @memberof bithenge_scope_t */
    165198int bithenge_scope_alloc_params(bithenge_scope_t *, int);
     199/** @memberof bithenge_scope_t */
    166200int bithenge_scope_set_param(bithenge_scope_t *, int, bithenge_node_t *);
     201/** @memberof bithenge_scope_t */
    167202int bithenge_scope_get_param(bithenge_scope_t *, int, bithenge_node_t **);
    168203

  • uspace/lib/bithenge/tree.c

    r1a3b953 r0784869  
    358358 * @param a, b Nodes to compare.
    359359 * @return EOK on success or an error code from errno.h.
    360  * @todo Add support for internal nodes.
    361  */
     360 * @todo Add support for internal nodes. */
    362361int bithenge_node_equal(bool *out, bithenge_node_t *a, bithenge_node_t *b)
    363362{

  • uspace/lib/bithenge/tree.h

    r1a3b953 r0784869  
    5656} bithenge_node_type_t;
    5757
     58/** A tree node. It can have any of the types in @a bithenge_node_type_t. */
    5859typedef struct bithenge_node_t {
    5960        /** @privatesection */
    … …  
    6162        unsigned int refs;
    6263        union {
     64                /** @privatesection */
    6365                const struct bithenge_internal_node_ops_t *internal_ops;
    6466                bool boolean_value;
    6567                bithenge_int_t integer_value;
    6668                struct {
     69                        /** @privatesection */
    6770                        const char *ptr;
    6871                        bool needs_free;
    … …  
    111114}
    112115
     116/** @memberof bithenge_node_t */
    113117void bithenge_node_dec_ref(bithenge_node_t *node);
    114118
    … …  
    126130}
    127131
     132/** @memberof bithenge_node_t */
    128133int bithenge_node_get(bithenge_node_t *, bithenge_node_t *,
    129134    bithenge_node_t **);
    … …  
    159164}
    160165
     166/** @memberof bithenge_node_t */
    161167int bithenge_init_internal_node(bithenge_node_t *,
    162168    const bithenge_internal_node_ops_t *);
     169/** @memberof bithenge_node_t */
    163170int bithenge_new_empty_internal_node(bithenge_node_t **);
     171/** @memberof bithenge_node_t */
    164172int bithenge_new_simple_internal_node(bithenge_node_t **, bithenge_node_t **,
    165173    bithenge_int_t, bool needs_free);
     174/** @memberof bithenge_node_t */
    166175int bithenge_new_boolean_node(bithenge_node_t **, bool);
     176/** @memberof bithenge_node_t */
    167177int bithenge_new_integer_node(bithenge_node_t **, bithenge_int_t);
     178/** @memberof bithenge_node_t */
    168179int bithenge_new_string_node(bithenge_node_t **, const char *, bool);
     180/** @memberof bithenge_node_t */
    169181int bithenge_node_equal(bool *, bithenge_node_t *, bithenge_node_t *);
    170182
Note: See TracChangeset for help on using the changeset viewer.