feat: add respective rst files for documentation

Benzammour · Oct 19, 2022 · 861a1ef · 861a1ef
1 parent 2e2a7aa
commit 861a1ef
Show file tree

Hide file tree

Showing 16 changed files with 110 additions and 21 deletions.
diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in
@@ -32,7 +32,7 @@ DOXYFILE_ENCODING      = UTF-8
 # title of most generated pages and in a few other places.
 # The default value is: My Project.
 
-PROJECT_NAME           = "Schnapsbrennen WS21/22"
+PROJECT_NAME           = "yobemag"
 
 # The PROJECT_NUMBER tag can be used to enter a project or revision number. This
 # could be handy for archiving the generated documentation or if some version
@@ -269,7 +269,7 @@ ALIASES                =
 # members will be omitted, etc.
 # The default value is: NO.
 
-OPTIMIZE_OUTPUT_FOR_C  = NO
+OPTIMIZE_OUTPUT_FOR_C  = YES
 
 # Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java or
 # Python sources only. Doxygen will then generate output that is more tailored
@@ -871,7 +871,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = ../src ../include ../python-plotting
+INPUT                  = ../src
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -1082,7 +1082,7 @@ USE_MDFILE_AS_MAINPAGE =
 # also VERBATIM_HEADERS is set to NO.
 # The default value is: NO.
 
-SOURCE_BROWSER         = NO
+SOURCE_BROWSER         = YES
 
 # Setting the INLINE_SOURCES tag to YES will include the body of functions,
 # classes and enums directly into the documentation.
@@ -1166,7 +1166,7 @@ VERBATIM_HEADERS       = NO
 # generated with the -Duse_libclang=ON option for CMake.
 # The default value is: NO.
 
-CLANG_ASSISTED_PARSING = NO
+CLANG_ASSISTED_PARSING = YES
 
 # If the CLANG_ASSISTED_PARSING tag is set to YES and the CLANG_ADD_INC_PATHS
 # tag is set to YES then doxygen will add the directory of each input to the
@@ -2227,7 +2227,7 @@ PERLMOD_MAKEVAR_PREFIX =
 # C-preprocessor directives found in the sources and include files.
 # The default value is: YES.
 
-ENABLE_PREPROCESSING   = YES
+ENABLE_PREPROCESSING   = NO
 
 # If the MACRO_EXPANSION tag is set to YES, doxygen will expand all macro names
 # in the source code. If set to NO, only conditional compilation will be
@@ -2236,7 +2236,7 @@ ENABLE_PREPROCESSING   = YES
 # The default value is: NO.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-MACRO_EXPANSION        = NO
+MACRO_EXPANSION        = YES
 
 # If the EXPAND_ONLY_PREDEF and MACRO_EXPANSION tags are both set to YES then
 # the macro expansion is limited to the macros specified with the PREDEFINED and
@@ -2295,7 +2295,7 @@ EXPAND_AS_DEFINED      =
 # The default value is: YES.
 # This tag requires that the tag ENABLE_PREPROCESSING is set to YES.
 
-SKIP_FUNCTION_MACROS   = YES
+SKIP_FUNCTION_MACROS   = NO
 
 #---------------------------------------------------------------------------
 # Configuration options related to external references

diff --git a/docs/cli.rst b/docs/cli.rst
@@ -0,0 +1,7 @@
+.. _cli:
+
+CLI
+===
+
+.. doxygenfile:: cli.h
+   :project: yobemag
diff --git a/docs/cpu.rst b/docs/cpu.rst
@@ -0,0 +1,7 @@
+.. _cpu:
+
+CPU
+===
+
+.. doxygenfile:: cpu.h
+   :project: yobemag
diff --git a/docs/index.rst b/docs/index.rst
@@ -1,2 +1,11 @@
 yobemag
 =======
+
+.. toctree::
+    :maxdepth: 3
+    :titlesonly:
+    :hidden:
+    :glob:
+
+    *
+
diff --git a/docs/lcd.rst b/docs/lcd.rst
@@ -0,0 +1,7 @@
+.. _lcd:
+
+LCD
+===
+
+.. doxygenfile:: lcd.h
+   :project: yobemag
diff --git a/docs/log.rst b/docs/log.rst
@@ -0,0 +1,7 @@
+.. _log:
+
+LOG
+===
+
+.. doxygenfile:: log.h
+   :project: yobemag
diff --git a/docs/mmu.rst b/docs/mmu.rst
@@ -0,0 +1,7 @@
+.. _mmu:
+
+MMU
+===
+
+.. doxygenfile:: mmu.h
+   :project: yobemag
diff --git a/docs/rom.rst b/docs/rom.rst
@@ -0,0 +1,7 @@
+.. _rom:
+
+ROM
+===
+
+.. doxygenfile:: rom.h
+   :project: yobemag
diff --git a/src/attributes.h b/src/attributes.h
@@ -0,0 +1,18 @@
+#ifndef YOBEMAG_ATTRIBUTES_H
+#define YOBEMAG_ATTRIBUTES_H
+
+#define ATTR_NORETURN __attribute__((__noreturn__))
+
+#define ATTR_FORMAT3 __attribute__((format(printf, 3, 4)))
+
+#define ATTR_FORMAT4 __attribute__((format(printf, 4, 5)))
+
+#define ATTR_ALWAYS_INLINE __attribute__((always_inline))
+
+#ifdef __GNU__
+	#define ATTR_PURE __attribute__((pure))
+#else
+	#define ATTR_PURE
+#endif
+
+#endif //YOBEMAG_ATTRIBUTES_H
diff --git a/src/cli.h b/src/cli.h
@@ -1,3 +1,5 @@
+/** @file */
+
 #ifndef YOBEMAG_CLI_H
 #define YOBEMAG_CLI_H
 

diff --git a/src/cpu.c b/src/cpu.c
@@ -3,6 +3,7 @@
 #include "mmu.h"
 #include "cpu.h"
 #include "log.h"
+#include "attributes.h"
 
 #define LO_NIBBLE_MASK (0x0F)
 //#define HI_NIBBLE_MASK (0xF0)
@@ -32,15 +33,15 @@ CPU cpu = {
     0,
 };
 
-__attribute((always_inline)) inline static void set_flag(uint8_t bit, Flag f) {
+ATTR_ALWAYS_INLINE inline static void set_flag(uint8_t bit, Flag f) {
 	cpu.AF.bytes.low |= bit << f;
 }
 
-__attribute((always_inline)) inline static void clear_flag(uint8_t bit, Flag f) {
+ATTR_ALWAYS_INLINE inline static void clear_flag(uint8_t bit, Flag f) {
 	cpu.AF.bytes.low &= (uint8_t) ~(bit << f);
 }
 
-__attribute((always_inline)) inline static void clear_flag_register(void) {
+ATTR_ALWAYS_INLINE inline static void clear_flag_register(void) {
 	cpu.AF.bytes.low = 0;
 }
 

diff --git a/src/cpu.h b/src/cpu.h
@@ -1,8 +1,12 @@
+/** @file */
+
 #ifndef YOBEMAG_CPU_H
 #define YOBEMAG_CPU_H
 
 #include <stdint.h>
 
+#include "attributes.h"
+
 /**
  * Encodes bit positions for flag register A
  */
@@ -50,11 +54,11 @@ typedef struct CPU {
 extern CPU cpu;
 
 void cpu_init(void);
-__attribute__((pure)) uint16_t cpu_get_cycle_count(void);
+ATTR_PURE uint16_t cpu_get_cycle_count(void);
 void cpu_step(void);
 
 
-__attribute__((pure)) uint16_t cpu_get_PC(void);
+ATTR_PURE uint16_t cpu_get_PC(void);
 void cpu_print_registers(void);
 
 void LD_REG_REG(uint8_t *register_one, uint8_t register_two);

diff --git a/src/lcd.h b/src/lcd.h
@@ -1,3 +1,5 @@
+/** @file */
+
 #ifndef YOBEMAG_LCD_H
 #define YOBEMAG_LCD_H
 

diff --git a/src/log.h b/src/log.h
@@ -1,7 +1,10 @@
+/** @file */
+
 #ifndef YOBEMAG_LOG_H
 #define YOBEMAG_LOG_H
 
 #include <stdio.h>
+#include "attributes.h"
 
 typedef enum LoggingLevel {
     DEBUG = -1,
@@ -21,15 +24,16 @@ void log_set_lvl(LoggingLevel log_lvl);
 /**
  * @brief 	Log a string to stderr with logging level ::FATAL formatted as
  * 			@p msg with parameters @p ...
- * 			This function is invoked by `#YOBEMAG_EXIT(msg, ...)`.
+ * 			This function is invoked by `#YOBEMAG_EXIT(msg, ...)`
  *
+ * @note This function does not return
  *
  * @param 	file_path 	Passed by `#YOBEMAG_EXIT(msg, ...)`. Indicates invocation site
  * @param 	line_number Passed by `#YOBEMAG_EXIT(msg, ...)`. Indicates specific invocation line
  * @param 	msg 		Format string for the log message
  * @param 	...			Parameters for format string
  */
-_Noreturn __attribute__((format(printf, 3, 4))) void log_exit(const char *file_path, int line_number, const char* msg, ...);
+ATTR_NORETURN ATTR_FORMAT3 void log_exit(const char *file_path, int line_number, const char* msg, ...);
 
 /**
  * @brief   Log a string to @p stream with logging level @p dbg_lvl, (printed as @p log_lvl_str),
@@ -41,7 +45,7 @@ _Noreturn __attribute__((format(printf, 3, 4))) void log_exit(const char *file_p
  * @param   msg         Format string for the log message
  * @param   ...         Parameters for format string
  */
-__attribute__((format(printf, 4, 5))) void log_str(LoggingLevel log_lvl, const char* log_lvl_str, FILE *stream,
+ATTR_FORMAT4 void log_str(LoggingLevel log_lvl, const char* log_lvl_str, FILE *stream,
 												   const char* msg, ...);
 
 /*
@@ -56,8 +60,7 @@ __attribute__((format(printf, 4, 5))) void log_str(LoggingLevel log_lvl, const c
 #define LOG_INFO(msg, ...)      log_str(INFO, "INFO", stdout, msg, ##__VA_ARGS__)
 #define LOG_WARNING(msg, ...)   log_str(WARNING, "WARNING", stdout, msg, ##__VA_ARGS__)
 #define LOG_ERROR(msg, ...)     log_str(ERROR, "ERROR", stderr, msg, ##__VA_ARGS__)
-#define LOG_FATAL(msg, ...)     log_str(FATAL, "FATAL", stderr, msg, ##__VA_ARGS__)
-#define YOBEMAG_EXIT(msg, ...)     log_exit(__FILE__, __LINE__, msg, ##__VA_ARGS__)
+#define YOBEMAG_EXIT(msg, ...)	log_exit(__FILE__, __LINE__, msg, ##__VA_ARGS__)
 
 #pragma clang diagnostic pop 
 

diff --git a/src/mmu.h b/src/mmu.h
@@ -1,3 +1,5 @@
+/** @file */
+
 #ifndef YOBEMAG_MEM_H
 #define YOBEMAG_MEM_H
 
@@ -6,10 +8,12 @@
 #include <string.h>
 #include <stdio.h>
 
+#include "attributes.h"
+
 void mmu_init(void);
-__attribute__((pure)) uint8_t mmu_get_byte(uint16_t addr);
+ATTR_PURE uint8_t mmu_get_byte(uint16_t addr);
 void mmu_write_byte(uint16_t dest_addr, uint8_t source_addr);
-__attribute__((pure)) uint16_t mmu_get_two_bytes(uint16_t addr);
+ATTR_PURE uint16_t mmu_get_two_bytes(uint16_t addr);
 void mmu_write_two_bytes(uint16_t dest_addr, uint16_t value);
 
 #endif //YOBEMAG_MEM_H
diff --git a/src/rom.h b/src/rom.h
@@ -1,10 +1,14 @@
+/** @file */
+
 #ifndef YOBEMAG_ROM_H
 #define YOBEMAG_ROM_H
 
 #include <stdint.h>
 
+#include "attributes.h"
+
 void rom_init(const char *file_name);
 void rom_destroy(void);
-__attribute__((pure)) uint8_t *get_rom_bytes(void);
+ATTR_PURE uint8_t *get_rom_bytes(void);
 
 #endif //YOBEMAG_ROM_H