Documentation

/**
 * @brief Merges two arrays and returns the merged array 
 * 
 * @detail Takes in 2 3x3 arrays and multiplies 
 * by multiplying the rows of Array1 with  
 * the columns of Array2 
 * 
 * @author CompEng0001
 * - September, 2023 
 * @date January, 2024- CompEng0001 
 * - Bug Fix 
 * @date January, 2025- CompEng0001
 * - Different bug fix 
 * @param int[] array1
 * @param int[] array2
 * @return int[] arrayOut 
 * @todo write the rest of the subroutine 
 */
int* arrayMerge(int* array1, int* array2);

Task 1: Doxygen with C

Here is an example output of what we are going to create: Output (redirects to new tab)

1. Create a new directory called Documentation and create the following files:

   • main.c
   • calculator.c
   • calculator.h

2. Modify the main.c code:

   Code

   /**
   * @file main.c
   * @brief Simple calculator program with basic operations.
   */
   #include <stdio.h>
   #include "calculator.h"
   
   /**
   * @brief Main function to demonstrate calculator operations.
   * @return 0 if successful, otherwise an error code.
   */
   int main(){
   
       int num1, num2;
   
       printf("Enter two numbers: ");
       scanf("%d %d", &num1, &num2);
   
       printf("Sum: %d\n", add(num1, num2));
       printf("Difference: %d\n", subtract(num1, num2));
   
       return 0;
   }
   

3. Modify the calculator.h file:

   Code

   #ifndef CALCULATOR_H_
   #define CALCULATOR_H_
   
   /**
   * @brief Adds two numbers.
   * @param a The first operand.
   * @param b The second operand.
   * @return The sum of a and b.
   */
   int add(int a, int b);
   
   /**
   * @brief Subtracts two numbers.
   * @param a The first operand.
   * @param b The second operand.
   * @return The result of subtracting b from a.
   */
   int subtract(int a, int b);
   
   #endif
   
   

4. Modify the calculator.c file:

   Code

   #include "calculator.h"
   
   int add(int a, int b) {
       return a + b;
   }
   
   int subtract(int a, int b) {
       return a - b;
   }
   

5. You can compile the code like normal, in case you can't remember how:

   Terminal

   $ gcc main.c calculator.c -o calculator.exe
   $ ./calculator.exe
   

6. To render the doxygen styled comments we need to use the doxygen.exe and a configuration file.

   • Run ./doxygen.exe -h in the command line to see the helper, read it and workout the argument to generate the configuration file called Doxyfile

   Answer...

   $ ./doxygen.exe -g
   

   Tip

   Remember to have extracted the doxygen.exe and libclang.dll to the same folder as the calculator source code, or update the $PATH to include /path/to/doxygen.exe

7. Now take the time to read the newly created Doxyfile, either use a text editor or display on the terminal using less:

   Terminal

   $ <code/less/nano/vim/vi> Doxyfile
   

   • Did you notice that there was rather a lot of configuration options, luckily they are well commented!

8. For the purpose of this exercise we are going to use the following configuration:

   Terminal

   Empty the Doxyfile to start a fresh

   $ echo > Doxyfile
   

   Code

   # Doxyfile for the project
   
   DOXYFILE_ENCODING      = UTF-8
   PROJECT_NAME           = "Calculator Documentation"
   PROJECT_NUMBER         = 1.0
   PROJECT_BRIEF          = "A simple calculator program with basic operations."
   
   OUTPUT_DIRECTORY       = ./docs
   CREATE_SUBDIRS         = NO
   
   # Add all the source files to the INPUT option
   INPUT                  = main.c \
                            calculator.h \
                            calculator.c
   
   RECURSIVE              = NO
   
   EXTRACT_ALL            = YES
   EXTRACT_PRIVATE        = YES
   EXTRACT_STATIC         = YES
   EXTRACT_LOCAL_CLASSES  = YES
   
   GENERATE_LATEX         = NO
   GENERATE_HTML          = YES
   

9. You should now see a folder docs/ in your current working directory, if you navigate you will find an index.html, which when opened in a browser will display the following:

   Doxygen Calculator Project Documentation Render

   

10. Consider expanding on the Calculator add some more features and explore more features with Doxygen: (https://www.doxygen.nl/examples.html)[https://www.doxygen.nl/examples.html]