Keep docs brief, consistent, and close to code. Prefer short C-style comments in implementation, full Doxygen in headers.
At the top of each file:
/* Module: Brief description of what this file provides (1–2 lines) */
Keep it short and factual.
One per file.
2. Function Documentation
Header Files (.h)
Use Doxygen-style comments for public API functions:
header file
/** Brief one-liner about function.
* @param param_name Description of parameter
* @return Description of return value (or void)
*/
void irq_install(uint8_t irq, irq_handler_t handler);
Implementation Files (.c)
Use a short C comment above the function for hover support:
Implementation file
/* Install handler for IRQ line 0..15 */
void irq_install(uint8_t irq, irq_handler_t handler) {
if (irq < 16) handlers[irq] = handler; /* assign handler if valid */
}
No full Doxygen duplication in .c.
Inline trailing comments are for minor clarifications only.
Static / Private Functions
If the function is static or local to .c:
Implementation file
/* Notify PIC of EOI for given IRQ */
static void irq_ack(uint8_t irq) {
outb(PIC1_CMD, PIC_EOI); /* master PIC */
if (irq >= 8) outb(PIC2_CMD, PIC_EOI); /* slave PIC */
}
3. Structs / Typedefs
One-line description above.
Trailing comments for fields.
Implementation file
/* IDTR descriptor for lidt */
typedef struct {
uint16_t limit; /* size in bytes - 1 */
uint32_t base; /* linear address */
} __attribute__((packed)) idtr_t;
4. Constants / Macros
Prefer named constants over magic numbers.
Add short description.
Implementation file
#define ICW4_8086 0x01 /* 8086/88 mode */
#define PIC_EOI 0x20 /* End-of-interrupt command */
5. Inline Assembly
Comment intent and unusual constraints.
Don’t restate the obvious.
Implementation file
__asm__ volatile ("outb %0, %1" :: "a"(value), "Nd"(port)); /* outb al,(port) */
6. Inline / Trailing Comments
Keep concise.
Align when convenient.
Implementation file
entry->offset1 = (uint32_t)isr & 0xFFFF; /* handler address bits 15..0 */
7. Tone
Imperative, concise, factual.
Avoid restating the obvious.