1.4. Documenting Structs

Effective documentation is crucial for maintaining a clean and understandable codebase. Caterpillar includes a feature to automatically generate documentation for your structs. By enabling this feature, you can reduce the need for manual updates and ensure that your structs are documented consistently. This feature can be activated with minimal code changes.

To enable the documentation feature globally, you simply need to set the appropriate flags. Below are the steps to enable it in both environments:

Python

Enable documentation feature

from caterpillar.py import set_struct_flags, S_REPLACE_TYPES

set_struct_flags(S_REPLACE_TYPES)

Caterpillar C

Enable documentation feature

from caterpillar.c import STRUCT_OPTIONS, S_REPLACE_TYPES

STRUCT_OPTIONS.add(S_REPLACE_TYPES)

Once this flag is set, Caterpillar will automatically replace the types of fields in structs with their respective descriptions. For example, the following reST code will generate simple class documentation for the NIBHeader` struct:

.. autoclass:: formats.nibarchive.NIBHeader
    :members:

results in:

class formats.nibarchive.NIBHeader(*, magic: bytes = b'NIBArchive', unknown_1: int, unknown_2: int, object_count: int, offset_objects: int, key_count: int, offset_keys: int, value_count: int, offset_values: int, class_name_count: int, offset_class_names: int)

Example class doc comment

magic: bytes

example field doc comment

unknown_1: int

second field doc comment

Tip

If you are working with Sphinx, you might need to enable autodoc_member_order = 'bysource' to display all struct members in the correct order.