Add ability to generate internal API documentation using Doxygen.

lib/barrier.h

@@ -1,15 +1,17 @@
 // SPDX-License-Identifier: GPL-2.0
 #ifndef BARRIER_H
 #define BARRIER_H
-/*
+/**
+ * \file
+ *
  * Provides a barrier synchronisation primitive.
  *
- * Copyright (C) 2020 Martin Whitaker.
+ * Copyright (C) 2020-2022 Martin Whitaker.
  */
 
 #include "spinlock.h"
 
-/*
+/**
  * A barrier object.
  */
 typedef struct
@@ -21,12 +23,12 @@ typedef struct
     spinlock_t      st2;
 } barrier_t;
 
-/*
+/**
  * Initialises the barrier to block the specified number of threads.
  */
 void barrier_init(barrier_t *barrier, int num_threads);
 
-/*
+/**
  * Waits for all threads to arrive at the barrier.
  */
 void barrier_wait(barrier_t *barrier);

lib/ctype.h

@@ -1,25 +1,27 @@
 // SPDX-License-Identifier: GPL-2.0
 #ifndef CTYPE_H
 #define CTYPE_H
-/*
+/**
+ * \file
+ *
  * Provides a subset of the functions normally provided by <ctype.h>.
  *
- * Copyright (C) 2020 Martin Whitaker.
+ * Copyright (C) 2020-2022 Martin Whitaker.
  */
 
-/*
+/**
  * If c is a lower-case letter, returns its upper-case equivalent, otherwise
  * returns c. Assumes c is an ASCII character.
  */
 int toupper(int c);
 
-/*
+/**
  * Returns 1 if c is a decimal digit, otherwise returns 0. Assumes c is an
  * ASCII character.
  */
 int isdigit(int c);
 
-/*
+/**
  * Returns 1 if c is a hexadecimal digit, otherwise returns 0. Assumes c is an
  * ASCII character.
  */

lib/print.h

@@ -1,28 +1,30 @@
 // SPDX-License-Identifier: GPL-2.0
 #ifndef PRINT_H
 #define PRINT_H
-/*
+/**
+ * \file
+ *
  * Provides functions to print strings and formatted values to the screen.
  *
- * Copyright (C) 2020 Martin Whitaker.
+ * Copyright (C) 2020-2022 Martin Whitaker.
  */
 
 #include <stdarg.h>
 #include <stdbool.h>
 #include <stdint.h>
 
-/*
+/**
  * Prints a single character on screen at location (row,col) and returns col+1.
  */
 int printc(int row, int col, char c);
 
-/*
+/**
  * Prints a string on screen starting at location (row,col) and returns the
  * next column after the string.
  */
 int prints(int row, int col, const char *str);
 
-/*
+/**
  * Prints a signed decimal number on screen starting at location (row,col) in
  * a field of at least length characters, optionally padding the number with
  * leading zeros, and optionally left-justifying instead of right-justifying
@@ -30,7 +32,7 @@ int prints(int row, int col, const char *str);
  */
 int printi(int row, int col, int value, int length, bool pad, bool left);
 
-/*
+/**
  * Prints an unsigned decimal number on screen starting at location (row,col)
  * in a field of at least length characters, optionally padding the number with
  * leading zeros, and optionally left-justifying instead of right-justifying in
@@ -38,7 +40,7 @@ int printi(int row, int col, int value, int length, bool pad, bool left);
  */
 int printu(int row, int col, uintptr_t value, int length, bool pad, bool left);
 
-/*
+/**
  * Prints an unsigned hexadecimal number on screen starting at location (row,col)
  * in a field of at least length characters, optionally padding the number with
  * leading zeros, and optionally left-justifying instead of right-justifying in
@@ -46,7 +48,7 @@ int printu(int row, int col, uintptr_t value, int length, bool pad, bool left);
  */
 int printx(int row, int col, uintptr_t value, int length, bool pad, bool left);
 
-/*
+/**
  * Prints a K<unit> value on screen starting at location (row,col) in a field of
  * at least length characters, optionally padding the number with leading zeros,
  * and optionally left-justifying instead of right-justifying in the field. The
@@ -55,7 +57,7 @@ int printx(int row, int col, uintptr_t value, int length, bool pad, bool left);
  */
 int printk(int row, int col, uintptr_t value, int length, bool pad, bool left);
 
-/*
+/**
  * Emulates the standard printf function. Printing starts at location (row,col).
  *
  * The conversion flags supported are:
@@ -77,7 +79,7 @@ int printk(int row, int col, uintptr_t value, int length, bool pad, bool left);
  */
 int printf(int row, int col, const char *fmt, ...);
 
-/*
+/**
  * The alternate form of printf.
  */
 int vprintf(int row, int col, const char *fmt, va_list args);

lib/read.h

@@ -1,15 +1,17 @@
 // SPDX-License-Identifier: GPL-2.0
 #ifndef READ_H
 #define READ_H
-/*
+/**
+ * \file
+ *
  * Provides a function to read a numeric value.
  *
- * Copyright (C) 2020 Martin Whitaker.
+ * Copyright (C) 2020-2022 Martin Whitaker.
  */
 
 #include <stdint.h>
 
-/*
+/**
  * Returns an unsigned numeric value entered on the keyboard. Echoes the
  * input to the display field located at (row,col), limiting it to field_width
  * characters. If the entered value is prefixed by "0x", assumes base 16,

lib/spinlock.h

@@ -1,20 +1,22 @@
 // SPDX-License-Identifier: GPL-2.0
 #ifndef SPINLOCK_H
 #define SPINLOCK_H
-/*
+/**
+ * \file
+ *
  * Provides a lightweight mutex synchronisation primitive.
  *
- * Copyright (C) 2020 Martin Whitaker.
+ * Copyright (C) 2020-2022 Martin Whitaker.
  */
 
 #include <stdbool.h>
 
-/*
+/**
  * A mutex object. Use spin_unlock() to initialise prior to first use.
  */
 typedef volatile bool spinlock_t;
 
-/*
+/**
  * Spins until the mutex is unlocked.
  */
 static inline void spin_wait(spinlock_t *lock)
@@ -26,7 +28,7 @@ static inline void spin_wait(spinlock_t *lock)
     }
 }
 
-/*
+/**
  * Spins until the mutex is unlocked, then locks the mutex.
  */
 static inline void spin_lock(spinlock_t *lock)
@@ -41,7 +43,7 @@ static inline void spin_lock(spinlock_t *lock)
     }
 }
 
-/*
+/**
  * Unlocks the mutex.
  */
 static inline void spin_unlock(spinlock_t *lock)

lib/string.h

@@ -1,15 +1,17 @@
 // SPDX-License-Identifier: GPL-2.0
 #ifndef STRING_H
 #define STRING_H
-/*
+/**
+ * \file
+ *
  * Provides a subset of the functions normally provided by <string.h>.
  *
- * Copyright (C) 2020 Martin Whitaker.
+ * Copyright (C) 2020-2022 Martin Whitaker.
  */
 
 #include <stddef.h>
 
-/*
+/**
  * Compares the first n bytes of the memory areas pointed to by s1 and s2
  * and returns 0 if all bytes are the same or the numerical difference
  * between the first mismatching byte in s1 (interpreted as an unsigned
@@ -17,32 +19,32 @@
  */
 int memcmp(const void *s1, const void *s2, size_t n);
 
-/*
+/**
  * Copies n bytes from the memory area pointed to by src to the memory area
  * pointed to by dest and returns a pointer to dest. The memory areas must
  * not overlap.
  */
 void *memcpy(void *dst, const void *src, size_t n);
 
-/*
+/**
  * Copies n bytes from the memory area pointed to by src to the memory area
  * pointed to by dest and returns a pointer to dest. The memory areas may
  * overlap.
  */
 void *memmove(void *dest, const void *src, size_t n);
 
-/*
+/**
  * Fills the first n bytes of the memory area pointed to by s with the byte
  * value c.
  */
 void *memset(void *s, int c, size_t n);
 
-/*
+/**
  * Returns the string length, excluding the terminating null character.
  */
 size_t strlen(const char *s);
 
-/*
+/**
  * Compares at most the first n characters in the strings s1 and s2 and
  * returns 0 if all characters are the same or the numerical difference
  * between the first mismatching character in s1 (interpreted as a signed
@@ -50,7 +52,7 @@ size_t strlen(const char *s);
  */
 int strncmp(const char *s1, const char *s2, size_t n);
 
-/*
+/**
  * Finds the first occurrence of the substring needle in the string haystack
  * and returns a pointer to the beginning of the located substring, or NULL
  * if the substring is not found.

lib/unistd.h

@@ -1,18 +1,20 @@
 // SPDX-License-Identifier: GPL-2.0
 #ifndef UNISTD_H
 #define UNISTD_H
-/*
+/**
+ * \file
+ *
  * Provides a subset of the functions normally provided by <unistd.h>.
  *
- * Copyright (C) 2020 Martin Whitaker.
+ * Copyright (C) 2020-2022 Martin Whitaker.
  */
 
-/*
+/**
  * Sleeps for at least usec microseconds.
  */
 void usleep(unsigned int usec);
 
-/*
+/**
  * Sleeps for at least sec seconds.
  */
 void sleep(unsigned int sec);