Enhanced Support for C "Class" Diagrams

[MrChocolateMoose]

Overview

For our project, many of our software components are written in C, although some are in C++. We run clang-uml on both of them.

For the C software components, we have options when creating useful sequence diagrams by specifying options like combine_free_functions_into_file_participants.

However for class diagrams, there aren't any options that I can find that allow for trying to bridge the gap to create C++ like class diagrams from C code.

Request

It would be very useful to have an option to automatically represent each file as a "class" that could contain:

• Public functions (exported/non-static functions)
• Private functions (static functions)
• Variables organized as "attributes"

Relationship arrows between neighboring "classes" would be based upon cross-file function calls, showing which modules depend on which other modules.

[MrChocolateMoose]

Example Header File: sensor_interface.h

#ifndef SENSOR_INTERFACE_H
#define SENSOR_INTERFACE_H

#include <stdint.h>
#include <stdbool.h>

/* Public types */
typedef enum {
    SENSOR_STATE_UNINIT = 0,
    SENSOR_STATE_INIT,
    SENSOR_STATE_RUNNING,
    SENSOR_STATE_ERROR
} sensor_state_t;

typedef struct {
    uint32_t timestamp;
    float value;
    uint8_t quality;
} sensor_data_t;

/* Error type */
typedef enum {
    SENSOR_OK = 0,
    SENSOR_ERROR_INIT,
    SENSOR_ERROR_READ,
    SENSOR_ERROR_PARAM,
    SENSOR_ERROR_STATE
} error_t;

/* Function prototypes */
error_t sensor_init(uint32_t configuration);
error_t sensor_read(sensor_data_t* data);
sensor_state_t sensor_get_state(void);
error_t sensor_register_callback(void (*callback)(sensor_data_t*));
void reset_error_counter(void);  /* Public reset function */

#endif /* SENSOR_INTERFACE_H */

Example Implementation File: sensor_interface.c

#include "sensor_interface.h"
#include "hardware_abstraction.h"
#include "logger.h"
#include <stddef.h>

/* Private variables */
static sensor_state_t current_state = SENSOR_STATE_UNINIT;
static uint8_t error_counter = 0;
static void (*data_ready_callback)(sensor_data_t*) = NULL;

/* Private function prototypes */
static error_t validate_sensor_reading(const sensor_data_t* data);
static void sensor_hw_init(uint32_t config);
static bool check_sensor_health(void);

/* Public functions */
error_t sensor_init(uint32_t configuration) {
    log_info("Initializing sensor with configuration %u", configuration);
    
    /* Initialize hardware */
    sensor_hw_init(configuration);
    
    /* Reset error counter */
    reset_error_counter();
    
    /* Set state to initialized */
    current_state = SENSOR_STATE_INIT;
    
    return SENSOR_OK;
}

error_t sensor_read(sensor_data_t* data) {
    if (data == NULL) {
        log_error("Null pointer provided to sensor_read");
        return SENSOR_ERROR_PARAM;
    }
    
    if (current_state != SENSOR_STATE_INIT && current_state != SENSOR_STATE_RUNNING) {
        log_error("Sensor not in valid state for reading");
        return SENSOR_ERROR_STATE;
    }
    
    error_t result = hw_read_sensor_registers(data);
    if (result != SENSOR_OK) {
        log_error("Failed to read sensor registers");
        return result;
    }
    
    result = validate_sensor_reading(data);
    if (result != SENSOR_OK) {
        return result;
    }
    
    current_state = SENSOR_STATE_RUNNING;
    
    /* Invoke callback if registered */
    if (data_ready_callback != NULL) {
        data_ready_callback(data);
    }
    
    return SENSOR_OK;
}

sensor_state_t sensor_get_state(void) {
    return current_state;
}

error_t sensor_register_callback(void (*callback)(sensor_data_t*)) {
    if (callback == NULL) {
        return SENSOR_ERROR_PARAM;
    }
    
    data_ready_callback = callback;
    return SENSOR_OK;
}

/* Public function implementation */
void reset_error_counter(void) {
    error_counter = 0;
}

/* Private functions */
static error_t validate_sensor_reading(const sensor_data_t* data) {
    if (data->quality < 50) {
        log_warning("Low quality sensor reading: %u", data->quality);
        error_counter++;
        
        if (error_counter > 5) {
            current_state = SENSOR_STATE_ERROR;
            log_error("Too many low quality readings, sensor in error state");
            return SENSOR_ERROR_READ;
        }
    }
    
    return SENSOR_OK;
}

static void sensor_hw_init(uint32_t config) {
    /* Reset hardware */
    hw_reset_sensor();
    
    /* Configure registers */
    hw_configure_sensor_registers(config);
    
    /* Enable sensor */
    hw_enable_sensor();
}

/* Private static function */
static bool check_sensor_health(void) {
    /* Check internal health indicators */
    if (error_counter > 3) {
        log_warning("Sensor health check failed: too many errors");
        return false;
    }
    
    /* Additional health checks could be performed here */
    
    return true;
}

Diagram

classDiagram
    class sensor_interface {
        <<C Module>>
        
        %% Private variables
        -sensor_state_t current_state
        -uint8_t error_counter
        
        %% Public functions
        +void (data_ready_callback)(sensor_data_t*)
        +error_t sensor_init(uint32_t configuration)
        +error_t sensor_read(sensor_data_t* data)
        +sensor_state_t sensor_get_state()
        +error_t sensor_register_callback(void (*callback)(sensor_data_t*))
        +void reset_error_counter()
        
        %% Private functions
        -error_t validate_sensor_reading(const sensor_data_t* data)
        -void sensor_hw_init(uint32_t config)
        -static bool check_sensor_health()
    }

    class hardware_abstraction {
        <<C Module>>
        +error_t hw_read_sensor_registers(sensor_data_t* data)
        +void hw_reset_sensor()
        +void hw_configure_sensor_registers(uint32_t config)
        +void hw_enable_sensor()
    }

    class logger {
        <<C Module>>
        +void log_info(const char* msg, ...)
        +void log_warning(const char* msg, ...)
        +void log_error(const char* msg, ...)
    }

    %% Module relationships and function calls
    sensor_interface --> hardware_abstraction : hw_read_sensor_registers()
    sensor_interface --> hardware_abstraction : hw_reset_sensor()
    sensor_interface --> hardware_abstraction : hw_configure_sensor_registers()
    sensor_interface --> hardware_abstraction : hw_enable_sensor()
    
    sensor_interface --> logger : log_info()
    sensor_interface --> logger : log_warning()
    sensor_interface --> logger : log_error()

Loading

[bkryza]

@MrChocolateMoose Thanks for the issue and example diagram, this definitely looks like an interesting use case - I'll look into that next week.