Dokumentowanie kodu w C

Cześć,
Funkcje w C opisuję w następujący sposób:

/**
 * @brief   Function to detects short or long press;
 *
 * @param   key_pin_state - actual pin state connected with key.
 *
 * @return  KEY_state_t - function returns actual key state.
 */

Jak opisywać struktyry, enumy, define?

Wystarczy sam brief?

/**
 * @brief  Buffer structure.
 */

Druga rzecz to wartości zwracane przez funkcje. Lepiej stosować enumy czy int8_t?

int8_t Ring_buffer_init(Ring_buffer_t *ring_buffer, uint32_t size)
{
	ring_buffer->buffer = (char*) malloc(size*sizeof(char));
	if(ring_buffer->buffer == NULL)
	{
		return -1;
	}
	ring_buffer->set_size = size;
	ring_buffer->actual_size = 0;
	ring_buffer->read_ptr = 0;
	ring_buffer->write_ptr = 0;
	return 0;
}

czy

RING_BUFFER_t Ring_buffer_init(Ring_buffer_t *ring_buffer, uint32_t size)
{
	ring_buffer->buffer = (char*) malloc(size*sizeof(char));
	if(ring_buffer->buffer == NULL)
	{
		return RING_BUFFER_ERROR;
	}

	ring_buffer->set_size = size;
	ring_buffer->actual_size = 0;
	ring_buffer->read_ptr = 0;
	ring_buffer->write_ptr = 0;

	return RING_BUFFER_OK;
}

Jeśli masz tylko dwa stany (OK i ERROR) to zwracaj bool. (w C musisz dodać #include <stdbool.h>)

RING_BUFFER_t to zła nazwa na kod wykonania funkcji. Nazwa typu sugeruje że jest tym buforem pierścienia (cokolwiek to jest) a nie że jest tylko statusem operacji.
Raczej ring_buffer_status_t albo coś… ale też nie wymyślaj osobnego typu dla każdej funkcji, która ma jakiś status zwracać.

Przy większej liczbie wartości nie mam zdania czy enum czy nie enum. Na jedno wychodzi.

Wydaje mi się że nadużywasz typów takich jak uint32_t, np. uint32_t size. Do określania rozmiaru bufora jest akurat size_t.

ring_buffer->buffer = (char*) malloc(size*sizeof(char));

sizeof(char) z definicji wynosi 1. Rzutowanie też jest opcjonalne w tym miejscu:

ring_buffer->buffer = malloc(size);

Jeśli opis miałby tak wyglądać, to lepiej żeby go nie było, bo tyle to (powinno być) widać po nazwie samego typu.

Pamiętaj też że im więcej opisów i komentarzy tym więcej przy nich roboty będzie potem, bo trzeba pilnować by były zawsze aktualne.