Contributing — libdicom documentation

# Contributing

## Coding style

Source code should be written following the K&R (Kernighan & Ritchie) style with a few modifications.

- Line length: max 80 characters

- Indentation: 4 spaces (no tabs)

- Braces:

  - Functions: opening brace at next line

  - Control statements (mandatory): opening brace at same line

- Spacing:

  - 2 lines between function definitions

  - 1 line between logical blocks within functions (and between variable declarations and definitions)

- Comments:

  - Documentation of functions and other symbols: balanced, multi-line `/** ... */` comments in reStructuredText format using field lists `:param:` and `:return:` to document function parameters and return values, respectively, and `:c:member:`, `:c:func:`, `:c:macro:`, `:c:struct:`, `:c:union:`, `:c:enum:`, `:c:enumerator:`, `:c:type:`, `:c:expr:`, `:c:var:` from the Sphinx C domain directive to cross-reference other C language constructs or to insert a C expression as inline code.

  - Inline comments in function body: single-line `//` C++ style comments

- Naming conventions:

  - Data structures (`struct` or `enum`) and types are named using upper camel case (e.g., `DcmDataSet`), while functions are named using all lower case with underscores (e.g., `dcm_dataset_create()`).

  - Names of `external` functions, data structures, and types that are declared in the `dicom.h` header file are prefixed with `dcm_` or `Dcm`. Names of `static` functions, types, or data structures declared in `*.c` files are never prefixed.

## Interface

The library exposes an “object-oriented” application programming interface (API), which provides data structures and functions to store, access, and manipulate the data.

To facilitate portability, the `dicom.h` header file is restricted to

- C99 version of the standard (C89 + Boolean type from `stdbool.h` + fixed-width integer types from `stdint.h`/`inttypes.h`)

- Opaque data types

- Clear, exact-width integer types (`int16_t`, `int32_t`, `int64_t`, `uint16_t`, `uint32_t`, and `uint64_t`)

- Minimal use of enums

## Implementation

The `dicom-data.c` (Part 5), `dicom-dict.c` (Part 6), and `dicom-file.c`

  and `dicom-parse.c` (Part 10) are implemented based on the C11 version of the standard.

The Data Set and Sequence data structures are implemented using the battletested uthash headers.

## Documentation

Documentation is written in reStructuredText format and HTML documents are autogenerated using Sphinx. API documentation is automatically extracted from the comments in the source code in the `dicom.h` header file via the Hawkmoth Sphinx C Autodoc extension, which relies on Clang to parse C code.

Documentation files are located under the `doc/source` directory of the repository. To build the documentation, install `libclang` development headers and the Python `venv` module, then build with `meson`:

> meson compile -C builddir html

The generated documentation files will then be located under the `builddir/html` directory. The `builddir/html/index.html` HTML document can be rendered in the web browser.

## Testing

Unit test cases are defined and run using check.

Test files are located under `/tests` and can be built and run using `meson`:

    meson test -C builddir

## Dynamic analysis

The source code can be analysed using valgrind.

For example:

    valgrind --leak-check=full dcm-dump data/test_files/sm_image.dcm

Unit testing and dynamic analysis can also be performed using the provided Dockerfile (located in the root of the repository):

    docker build -t dcm-testing .
    docker run dcm-testing