Move tests and headers and add doxygen support

CMakeLists.txt

@@ -1,17 +1,23 @@
 cmake_minimum_required(VERSION 3.16)
-project(microirc LANGUAGES C)
+project(
+	uIRC
+	VERSION 2021.01.03
+	DESCRIPTION "Simple and lightweight IRC protocol helper"
+	LANGUAGES C
+)
 
 include(GNUInstallDirs)
 
-set(UIRC_VERSION "2021.01.03")
+set(UIRC_VERSION "${PROJECT_VERSION}")
 add_compile_definitions(UIRC_VERSION="${UIRC_VERSION}")
 
-OPTION(BUILD_HELPERS    "Build message helpers"         ON )
-OPTION(BUILD_VALIDATORS "Build message validators"      ON )
-OPTION(BUILD_IRCV3      "Build IRCv3 components"        ON )
-OPTION(BUILD_TESTS      "Build tests for ctest"         OFF)
-OPTION(CODE_ANALYZER    "Analyze the code statically"   OFF)
-OPTION(CODE_COVERAGE    "Build with coverage tools"     OFF)
+OPTION(BUILD_HELPERS    "Build message helpers"            ON )
+OPTION(BUILD_VALIDATORS "Build message validators"         ON )
+OPTION(BUILD_IRCV3      "Build IRCv3 components"           ON )
+OPTION(BUILD_TESTS      "Build tests for ctest"            OFF)
+OPTION(BUILD_DOCS       "Build documentation with doxygen" OFF)
+OPTION(CODE_ANALYZER    "Analyze the code statically"      OFF)
+OPTION(CODE_COVERAGE    "Build with coverage tools"        OFF)
 
 set(UIRC_SOURCE
 	src/assemblers.c
@@ -23,15 +29,15 @@ set(UIRC_SOURCE
 )
 
 set(UIRC_HEADERS
-	src/assemblers.h
-	src/commands.h
-	src/converters.h
-	src/errors.h
-	src/modes.h
-	src/replies.h
-	src/tokenizers.h
-	src/types.h
-	src/uirc.h
+	src/public/assemblers.h
+	src/public/commands.h
+	src/public/converters.h
+	src/public/errors.h
+	src/public/modes.h
+	src/public/replies.h
+	src/public/tokenizers.h
+	src/public/types.h
+	src/public/uirc.h
 )
 
 #
@@ -45,8 +51,8 @@ if (BUILD_IRCV3)
 		src/capabilities.c
 	)
 	set(UIRC_HEADERS ${UIRC_HEADERS}
-		src/tags.h
-		src/capabilities.h
+		src/public/tags.h
+		src/public/capabilities.h
 	)
 endif()
 if (BUILD_VALIDATORS)
@@ -56,7 +62,7 @@ if (BUILD_VALIDATORS)
 		src/validators.c
 	)
 	set(UIRC_HEADERS ${UIRC_HEADERS}
-		src/validators.h
+		src/public/validators.h
 	)
 endif()
 if (BUILD_HELPERS)
@@ -68,7 +74,7 @@ if (BUILD_TESTS)
 	enable_testing()
 
 	macro(buildtest name source)
-		add_executable(${source} tests/${source}.c)
+		add_executable(${source} src/tests/${source}.c)
 		target_link_libraries(${source} uirc)
 		add_test(NAME ${name} COMMAND ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/${source})
 	endmacro()
@@ -92,11 +98,24 @@ if (BUILD_TESTS)
 		endif()
 	endif()
 endif()
+if(BUILD_DOCS)
+	find_package(Doxygen REQUIRED)
+	if (DOXYGEN_FOUND)
+		set(DOXYGEN_SOURCE_BROWSER       YES)
+		set(DOXYGEN_EXTRACT_ALL          YES)
+		set(DOXYGEN_MACRO_EXPANSION      YES)
+		doxygen_add_docs(docgen
+			${UIRC_HEADERS}
+			README.md
+			ALL
+		)
+	endif()
+endif()
+
 
 add_library(uirc ${UIRC_SOURCE})
 
 set(CMAKE_C_FLAGS_RELEASE "${CMAKE_C_FLAGS_RELEASE} -Werror")
-add_compile_options(-pedantic)
 if (CMAKE_C_COMPILER_ID STREQUAL "GNU")
 	add_compile_options(
 		-Wall
@@ -115,6 +134,7 @@ if (CMAKE_C_COMPILER_ID STREQUAL "GNU")
 		-Wunsafe-loop-optimizations
 		-Wparentheses
 		-fstack-check
+		-pedantic
 	)
 	if (CODE_ANALYZER)
 		add_compile_options(-fanalyzer)
@@ -124,6 +144,7 @@ elseif (CMAKE_C_COMPILER_ID STREQUAL "Clang")
 		-Weverything
 		-Wno-padded
 		-Wno-disabled-macro-expansion
+		-pedantic
 	)
 	if (CODE_COVERAGE)
 		add_compile_options(-fprofile-instr-generate -fcoverage-mapping)

src/assemblers.c

@@ -16,14 +16,15 @@
  *  along with uIRC.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-#include "assemblers.h"
+#include "public/assemblers.h"
 
-#include "commands.h"
-#include "errors.h"
-#include "memory.h"
-#include "modes.h"
-#include "tags.h"
-#include "types.h"
+#include "private/mappings.h"
+#include "private/memory.h"
+#include "public/commands.h"
+#include "public/errors.h"
+#include "public/modes.h"
+#include "public/tags.h"
+#include "public/types.h"
 
 #include <stdbool.h>
 #include <stdio.h>

src/capabilities.c

@@ -16,7 +16,7 @@
  *  along with uIRC.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-#include "capabilities.h"
+#include "public/capabilities.h"
 
 #include <stdlib.h>
 #include <string.h>

src/commands.c

@@ -16,7 +16,7 @@
  *  along with uIRC.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-#include "commands.h"
+#include "public/commands.h"
 
 const char* const IRC_Cmds[] = { [ADMIN] = "ADMIN",     [AWAY] = "AWAY",       [CONNECT] = "CONNECT",   [DIE] = "DIE",
 	                         [ERROR] = "ERROR",     [INFO] = "INFO",       [INVITE] = "INVITE",     [ISON] = "ISON",

src/converters.c

@@ -16,10 +16,10 @@
  *  along with uIRC.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-#include "converters.h"
+#include "public/converters.h"
 
-#include "commands.h"
-#include "errors.h"
+#include "public/commands.h"
+#include "public/errors.h"
 
 #include <string.h>
 

src/memory.c

@@ -16,7 +16,7 @@
  *  along with uIRC.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-#include "memory.h"
+#include "private/memory.h"
 
 #include <stdbool.h>
 #include <string.h>

src/private/mappings.h

@@ -16,24 +16,18 @@
  *  along with uIRC.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-#include "types.h"
+#include "../public/types.h"
 
 #include <stdbool.h>
+#include <stdlib.h>
+#include <sys/types.h>
 
-#ifndef UIRC_GUARD_TOKENIZERS
-#define UIRC_GUARD_TOKENIZERS
+#ifndef UIRC_GUARD_MAPPINGS
+#define UIRC_GUARD_MAPPINGS
 
-#ifdef UIRC_IRCV3
-signed int Tok_tags(char* str, IRC_Tags* out);
-#endif /* UIRC_IRCV3 */
-
-signed int Tok_user(char* str, IRC_User* out, bool useorig);
-signed int Tok_mesg(char* str, IRC_Message* out);
-
-#ifdef UIRC_HELPERS
-void Tok_cmd_PING(IRC_Message* mesg, char** source, char** target);
-void Tok_FArgOpt(IRC_Message* mesg, char** optarg, char** reqarg);
-#endif /* UIRC_HELPERS */
-
-#endif /* UIRC_GUARD_TOKENIZERS */
+struct tagmapping {
+	const char* const name;
+	IRC_Tag*          assg;
+};
 
+#endif /* UIRC_GUARD_MAPPINGS */

src/public/capabilities.h

@@ -19,7 +19,12 @@
 #ifndef UIRC_GUARD_CAPABILITIES
 #define UIRC_GUARD_CAPABILITIES
 
-/* IRCv3 Supported features bits */
+/*!
+ * \brief List of capabilities to be used as a bitmask
+ *
+ * \sa CAPBIT
+ * \sa https://ircv3.net/registry#capabilities
+ */
 enum caps {
 	CAP_ACCOUNT_NOTIFY    = 1,
 	CAP_ACCOUNT_TAG       = 2,
@@ -42,11 +47,32 @@ enum caps {
 	CAP_TLS               = 19,
 	CAP_USERHOST_IN_NAMES = 20,
 };
+/*!
+ * \brief Converts capability to bitmask value
+ *
+ * \param[in] cap Capability bit from \link caps \endlink
+ */
 #define CAPBIT(cap) (1 << (cap))
 
 #ifdef UIRC_HELPERS
+/*!
+ * \brief Converts a string of capabilities to a bitmask
+ *
+ * This function converts all the capabilities from \link IRC_v3_Caps \endlink to a bitmask
+ * \param[in] caps String of capabilities separated by space
+ * \sa CAPBIT
+ * \sa caps
+ * \sa https://ircv3.net/registry#capabilities
+ */
 int Tok_CAPS(char* caps);
 #endif /* UIRC_HELPERS */
+
+/*!
+ * \brief String representations of IRCv3 capabilities
+ *
+ * This contains the capabilities from \link caps \endlink in their string form.
+ * \sa https://ircv3.net/registry#capabilities
+ */
 extern const char* const IRC_v3_Caps[];
 
 #endif /* UIRC_GUARD_CAPABILITIES */

src/public/tags.h

@@ -16,20 +16,11 @@
  *  along with uIRC.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-#include "types.h"
-
-#include <stdbool.h>
-#include <stdlib.h>
 #include <sys/types.h>
 
 #ifndef UIRC_GUARD_TAGS
 #define UIRC_GUARD_TAGS
 
-struct tagmapping {
-	const char* const name;
-	IRC_Tag*          assg;
-};
-
 #ifdef UIRC_HELPERS
 size_t Assm_tag_timestamp(char* buf, size_t len, time_t time);
 #endif /* UIRC_HELPERS */

src/public/tokenizers.h

@@ -0,0 +1,79 @@
+/*
+ *  This file is part of uIRC. (https://git.redxen.eu/caskd/uIRC)
+ *  Copyright (c) 2019, 2020 Alex-David Denes
+ *
+ *  uIRC is free software: you can redistribute it and/or modify
+ *  it under the terms of the GNU General Public License as published by
+ *  the Free Software Foundation, either version 3 of the License, or
+ *  any later version.
+ *
+ *  uIRC is distributed in the hope that it will be useful,
+ *  but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *  GNU General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public License
+ *  along with uIRC.  If not, see <https://www.gnu.org/licenses/>.
+ */
+
+#include "types.h"
+
+#include <stdbool.h>
+
+#ifndef UIRC_GUARD_TOKENIZERS
+#define UIRC_GUARD_TOKENIZERS
+
+#ifdef UIRC_IRCV3
+/*!
+ * \brief Tokenize IRCv3 tags
+ *
+ * This function parses IRCv3 tags according to the specification at
+ * \param[in]  str     String containing a IRC source with or without the ':' prefix
+ * \param[out] out     Allocated IRC_User structure
+ * \param[in]  useorig If '\%orig' should be considered in the parsing
+ */
+signed int Tok_tags(char* str, IRC_Tags* out);
+#endif /* UIRC_IRCV3 */
+
+/*!
+ * \brief Tokenize a IRC message source.
+ *
+ * This function takes the source part of a message, pointing struct elements to parts of it.
+ * \param[in] str     String containing a IRC source with or without the ':' prefix
+ * \param[out] out     Allocated IRC_User structure
+ * \param[in] useorig If '\%orig' should be considered in the parsing
+ */
+signed int Tok_user(char* str, IRC_User* out, bool useorig);
+
+/*!
+ * \brief Tokenize a IRC message string.
+ *
+ * This function takes a IRC Message and attempts to tokenize/parse it, pointing every element found to it's respective struct element
+ * \param[in] str String containing a IRC message without the ending '\\r\\n'
+ * \param[out] out Allocated IRC_Message structure
+ */
+signed int Tok_mesg(char* str, IRC_Message* out);
+
+#ifdef UIRC_HELPERS
+/*!
+ * \brief A PING tokenizer/parser
+ *
+ * This function is a simple helper to get the source and target of a PING since the RFC has a "interesting" implementation
+ * \param[in] mesg IRC_Message struct containing the PING message
+ * \param[out] source Source of the PING (server)
+ * \param[out] target Target of the PING (server or client)
+ */
+void Tok_cmd_PING(IRC_Message* mesg, char** source, char** target);
+/*!
+ * \brief Tokenizer for cases where the first argument is optional
+ *
+ * This function is a private helper for cases where the first argument might be missing but the second isn't
+ * \param[in] mesg IRC_Message struct
+ * \param[out] optarg Optional argument if given or NULL
+ * \param[out] target Required argument
+ */
+void Tok_FArgOpt(IRC_Message* mesg, char** optarg, char** reqarg);
+#endif /* UIRC_HELPERS */
+
+#endif /* UIRC_GUARD_TOKENIZERS */
+

src/public/types.h

@@ -21,6 +21,8 @@
 #ifndef UIRC_GUARD_TYPES
 #define UIRC_GUARD_TYPES
 
+/*!
+ */
 typedef unsigned short IRC_Command;
 
 #ifdef UIRC_IRCV3

src/string.c

@@ -16,7 +16,7 @@
  *  along with uIRC.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-#include "string.h"
+#include "private/string.h"
 
 #include <stdio.h>
 

src/tags.c

@@ -16,7 +16,7 @@
  *  along with uIRC.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-#include "tags.h"
+#include "public/tags.h"
 
 #include <time.h>
 

src/tests/capbitmask.c

@@ -16,7 +16,7 @@
  *  along with uIRC.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-#include "../src/capabilities.h"
+#include "../public/capabilities.h"
 
 #include <stdio.h>
 #include <stdlib.h>

src/tests/junk.c

@@ -16,8 +16,8 @@
  *  along with uIRC.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-#include "../src/tokenizers.h"
-#include "../src/types.h"
+#include "../public/tokenizers.h"
+#include "../public/types.h"
 
 #include <stdio.h>
 #include <stdlib.h>

src/tests/msgassm.c

@@ -16,9 +16,9 @@
  *  along with uIRC.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-#include "../src/assemblers.h"
-#include "../src/commands.h"
-#include "../src/types.h"
+#include "../public/assemblers.h"
+#include "../public/commands.h"
+#include "../public/types.h"
 
 #include <stdio.h>
 #include <stdlib.h>

src/tests/notrail.c

@@ -16,8 +16,8 @@
  *  along with uIRC.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-#include "../src/tokenizers.h"
-#include "../src/types.h"
+#include "../public/tokenizers.h"
+#include "../public/types.h"
 
 #include <stdio.h>
 #include <stdlib.h>

src/tests/numericmds.c

@@ -16,9 +16,9 @@
  *  along with uIRC.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-#include "../src/assemblers.h"
-#include "../src/replies.h"
-#include "../src/types.h"
+#include "../public/assemblers.h"
+#include "../public/replies.h"
+#include "../public/types.h"
 
 #include <stdio.h>
 #include <stdlib.h>

src/tests/overflow.c

@@ -16,9 +16,9 @@
  *  along with uIRC.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-#include "../src/assemblers.h"
-#include "../src/commands.h"
-#include "../src/types.h"
+#include "../public/assemblers.h"
+#include "../public/commands.h"
+#include "../public/types.h"
 
 #include <stdio.h>
 #include <stdlib.h>

src/tests/prefixassm.c

@@ -16,8 +16,8 @@
  *  along with uIRC.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-#include "../src/assemblers.h"
-#include "../src/types.h"
+#include "../public/assemblers.h"
+#include "../public/types.h"
 
 #include <stdio.h>
 #include <stdlib.h>

src/tests/spacedargs.c

@@ -16,9 +16,9 @@
  *  along with uIRC.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-#include "../src/commands.h"
-#include "../src/tokenizers.h"
-#include "../src/types.h"
+#include "../public/commands.h"
+#include "../public/tokenizers.h"
+#include "../public/types.h"
 
 #include <stdio.h>
 #include <stdlib.h>

src/tests/strtokmr.c

@@ -16,7 +16,7 @@
  *  along with uIRC.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-#include "../src/string.h"
+#include "../private/string.h"
 
 #include <stdio.h>
 #include <stdlib.h>

src/tests/tagassm.c

@@ -16,8 +16,8 @@
  *  along with uIRC.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-#include "../src/assemblers.h"
-#include "../src/types.h"
+#include "../public/assemblers.h"
+#include "../public/types.h"
 
 #include <stdio.h>
 #include <stdlib.h>

src/tests/tagtok.c

@@ -16,8 +16,8 @@
  *  along with uIRC.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-#include "../src/tokenizers.h"
-#include "../src/types.h"
+#include "../public/tokenizers.h"
+#include "../public/types.h"
 
 #include <stdio.h>
 #include <stdlib.h>

src/tests/timestamp.c

@@ -16,8 +16,8 @@
  *  along with uIRC.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-#include "../src/tags.h"
-#include "../src/types.h"
+#include "../public/tags.h"
+#include "../public/types.h"
 
 #include <stdio.h>
 #include <stdlib.h>

src/tests/tokenizer.c

@@ -16,8 +16,8 @@
  *  along with uIRC.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-#include "../src/commands.h"
-#include "../src/tokenizers.h"
+#include "../public/commands.h"
+#include "../public/tokenizers.h"
 
 #include <stdio.h>
 #include <stdlib.h>

src/tokenizers.c

@@ -16,14 +16,15 @@
  *  along with uIRC.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-#include "tokenizers.h"
+#include "public/tokenizers.h"
 
-#include "commands.h"
-#include "converters.h"
-#include "errors.h"
-#include "string.h"
-#include "tags.h"
-#include "types.h"
+#include "private/mappings.h"
+#include "private/string.h"
+#include "public/commands.h"
+#include "public/converters.h"
+#include "public/errors.h"
+#include "public/tags.h"
+#include "public/types.h"
 
 #include <ctype.h>
 #include <stdbool.h>

src/validators.c

@@ -16,10 +16,10 @@
  *  along with uIRC.  If not, see <https://www.gnu.org/licenses/>.
  */
 
-#include "validators.h"
+#include "public/validators.h"
 
-#include "errors.h"
-#include "types.h"
+#include "public/errors.h"
+#include "public/types.h"
 
 #include <stdio.h>
 #include <string.h>