Add documentation to v2script::Parser

Add documentation to csv::Parser
Add documentation to detail::BasicParser

Move load_from_file(const detail::Has_c_str) out of source files

3 files changed, 147 insertions, 4 deletions

diff --git a/include/openvic-dataloader/csv/Parser.hpp b/include/openvic-dataloader/csv/Parser.hpp
index fadaf3a..5807181 100644
--- a/include/openvic-dataloader/csv/Parser.hpp
+++ b/include/openvic-dataloader/csv/Parser.hpp
@@ -5,31 +5,92 @@
 
 namespace ovdl::csv {
 	enum class EncodingType {
+		/// Support for Windows-1252 ANSI standard
 		Windows1252,
+		/// Support for UTF-8 Unicode standard
 		Utf8
 	};
 
+	/// Parser for CSV files
+	/// @tparam Encoding The type of encoding used for this parser
 	template<EncodingType Encoding = EncodingType::Windows1252>
 	class Parser final : public detail::BasicParser {
 	public:
 		Parser();
 
+		/// Makes a parse buffer from data to data+size
+		/// @param data Initial character buffer memory position
+		/// @param size End distance from data for buffer
+		/// @return Parser that calls load_from_buffer(const char* data, std::size_t size)
+		/// @sa load_from_buffer(const char* data, std::size_t size)
 		static Parser from_buffer(const char* data, std::size_t size);
+		/// Makes a parse buffer from data to end
+		/// @param start Initial character buffer memory position
+		/// @param end End character buffer memory position
+		/// @return Parser that calls load_from_buffer(const char* start, const char* end)
+		/// @sa load_from_buffer(const char* data, const char* end)
 		static Parser from_buffer(const char* start, const char* end);
+		/// Makes a parse buffer from a string_view
+		/// @param string string_view to create a buffer from
+		/// @return Parser that calls load_from_string(const std::string_view string)
+		/// @sa load_from_string(const std::string_view string)
 		static Parser from_string(const std::string_view string);
+		/// Makes a parse buffer based on the file path
+		/// @param path The file path to supply for the buffer
+		/// @return Parser that calls load_from_file(const char* path)
+		/// @sa load_from_file(const char* path)
 		static Parser from_file(const char* path);
+		/// Makes a parse buffer based on a filesystem::path
+		/// @param path The file path to supply for the buffer
+		/// @return Parser that calls load_from_file(const std::filesystem::path& path)
+		/// @sa load_from_file(const std::filesystem::path& path)
 		static Parser from_file(const std::filesystem::path& path);
+		/// Makes a parse buffer based on any type that has a `const char* c_str()` function
+		/// @param path The file path to supply for the buffer
+		/// @return Parser that calls from_file(path.c_str())
+		/// @sa from_file(const char* path)
+		static Parser from_file(const detail::Has_c_str auto& path) {
+			return from_file(path.c_str());
+		}
 
+		/// Loads a parse buffer from data to data+size
+		/// @param data Initial character buffer memory position
+		/// @param size End distance from data for buffer
+		/// @return Parser& *this
 		constexpr Parser& load_from_buffer(const char* data, std::size_t size);
+		/// Loads a parse buffer from data to end
+		/// @param start Initial character buffer memory position
+		/// @param end End character buffer memory position
+		/// @return Parser& *this
 		constexpr Parser& load_from_buffer(const char* start, const char* end);
+		/// Loads a parse buffer from a string_view
+		/// @param string string_view to create a buffer from
+		/// @return Parser& *this
 		constexpr Parser& load_from_string(const std::string_view string);
+		/// Loads a parse buffer based on the file path
+		/// @param path The file path to supply for the buffer
+		/// @return Parser& *this
 		constexpr Parser& load_from_file(const char* path);
+		/// Loads a parse buffer based on a filesystem::path
+		/// @param path The file path to supply for the buffer
+		/// @return Parser& *this
 		Parser& load_from_file(const std::filesystem::path& path);
 
-		constexpr Parser& load_from_file(const detail::Has_c_str auto& path);
+		/// Loads a parse buffer based on any type that has a `const char* c_str()` function
+		/// @param path The file path to supply for the buffer
+		/// @return Parser& *this
+		constexpr Parser& load_from_file(const detail::Has_c_str auto& path) {
+			return load_from_file(path.c_str());
+		}
 
+		/// Performs a CSV file parse over the buffer
+		/// @return true Successfully parsed a CSV buffer
+		/// @return false Failed to parse a CSV buffer
+		/// @note Warnings still produce true
 		bool parse_csv();
 
+		/// Get a vector LineObjects
+		/// @return const std::vector<csv::LineObject>&
 		const std::vector<csv::LineObject>& get_lines() const;
 
 		Parser(Parser&&);
diff --git a/include/openvic-dataloader/detail/BasicParser.hpp b/include/openvic-dataloader/detail/BasicParser.hpp
index 5493804..0f77439 100644
--- a/include/openvic-dataloader/detail/BasicParser.hpp
+++ b/include/openvic-dataloader/detail/BasicParser.hpp
@@ -10,6 +10,9 @@
 #include <openvic-dataloader/detail/Concepts.hpp>
 
 namespace ovdl::detail {
+	/// Common interface for Parsers
+	///
+	/// Derive from to build new Parsers
 	class BasicParser {
 	public:
 		BasicParser();
diff --git a/include/openvic-dataloader/v2script/Parser.hpp b/include/openvic-dataloader/v2script/Parser.hpp
index fb9022a..0ada9f2 100644
--- a/include/openvic-dataloader/v2script/Parser.hpp
+++ b/include/openvic-dataloader/v2script/Parser.hpp
@@ -23,29 +23,108 @@ namespace ovdl::v2script {
 	public:
 		Parser();
 
+		/// Makes a parse buffer from data to data+size
+		/// @param data Initial character buffer memory position
+		/// @param size End distance from data for buffer
+		/// @return Parser that calls load_from_buffer(const char* data, std::size_t size)
+		/// @sa load_from_buffer(const char* data, std::size_t size)
 		static Parser from_buffer(const char* data, std::size_t size);
+		/// Makes a parse buffer from data to end
+		/// @param start Initial character buffer memory position
+		/// @param end End character buffer memory position
+		/// @return Parser that calls load_from_buffer(const char* start, const char* end)
+		/// @sa load_from_buffer(const char* data, const char* end)
 		static Parser from_buffer(const char* start, const char* end);
+		/// Makes a parse buffer from a string_view
+		/// @param string string_view to create a buffer from
+		/// @return Parser that calls load_from_string(const std::string_view string)
+		/// @sa load_from_string(const std::string_view string)
 		static Parser from_string(const std::string_view string);
+		/// Makes a parse buffer based on the file path
+		/// @param path The file path to supply for the buffer
+		/// @return Parser that calls load_from_file(const char* path)
+		/// @sa load_from_file(const char* path)
 		static Parser from_file(const char* path);
+		/// Makes a parse buffer based on a filesystem::path
+		/// @param path The file path to supply for the buffer
+		/// @return Parser that calls load_from_file(const std::filesystem::path& path)
+		/// @sa load_from_file(const std::filesystem::path& path)
 		static Parser from_file(const std::filesystem::path& path);
-
+		/// Makes a parse buffer based on any type that has a `const char* c_str()` function
+		/// @param path The file path to supply for the buffer
+		/// @return Parser that calls from_file(path.c_str())
+		/// @sa from_file(const char* path)
+		static Parser from_file(const detail::Has_c_str auto& path) {
+			return from_file(path.c_str());
+		}
+
+		/// Loads a parse buffer from data to data+size
+		/// @param data Initial character buffer memory position
+		/// @param size End distance from data for buffer
+		/// @return Parser& *this
 		constexpr Parser& load_from_buffer(const char* data, std::size_t size);
+		/// Loads a parse buffer from data to end
+		/// @param start Initial character buffer memory position
+		/// @param end End character buffer memory position
+		/// @return Parser& *this
 		constexpr Parser& load_from_buffer(const char* start, const char* end);
+		/// Loads a parse buffer from a string_view
+		/// @param string string_view to create a buffer from
+		/// @return Parser& *this
 		constexpr Parser& load_from_string(const std::string_view string);
+		/// Loads a parse buffer based on the file path
+		/// @param path The file path to supply for the buffer
+		/// @return Parser& *this
 		constexpr Parser& load_from_file(const char* path);
+		/// Loads a parse buffer based on a filesystem::path
+		/// @param path The file path to supply for the buffer
+		/// @return Parser& *this
 		Parser& load_from_file(const std::filesystem::path& path);
 
-		constexpr Parser& load_from_file(const detail::Has_c_str auto& path);
-
+		/// Loads a parse buffer based on any type that has a `const char* c_str()` function
+		/// @param path The file path to supply for the buffer
+		/// @return Parser& *this
+		constexpr Parser& load_from_file(const detail::Has_c_str auto& path) {
+			return load_from_file(path.c_str());
+		}
+
+		/// Performs a less interpretive file parse over the buffer
+		/// @return true Successfully parsed a simple text buffer
+		/// @return false Failed to parse a simple text buffer
+		/// @note Warnings still produce true
+		/// @sa src/openvic-dataloader/v2script/SimpleGrammar.hpp
 		bool simple_parse();
+		/// Performs an event file parse over the buffer
+		/// @return true Successfully parsed an event file
+		/// @return false Failed to parse an event file
+		/// @note Warnings still produce true
+		/// @sa src/openvic-dataloader/v2script/EventGrammar.hpp
 		bool event_parse();
+		/// Performs a decision file parse over the buffer
+		/// @return true Successfully parsed a decision file
+		/// @return false Failed to parse an decision file
+		/// @note Warnings still produce true
+		/// @sa src/openvic-dataloader/v2script/DecisionGrammar.hpp
 		bool decision_parse();
 
+		/// @brief Gets the top-level FileNode pointer that was parsed
+		/// @return const FileNode*
 		const FileNode* get_file_node() const;
 
+		/// Generates a map of line/column locations based on the buffer
+		/// @note Call after parse, this relies on parsed nodes
+		/// @note Currently ignores event and decision parsing
 		void generate_node_location_map();
 
+		/// Gets the node's begin line and column
+		/// @param node Node pointer to get the beginning line and column of
+		/// @return const ast::Node::line_col
 		const ast::Node::line_col get_node_begin(const ast::NodeCPtr node) const;
+		/// Gets the node's end line and column
+		///
+		/// If a node does not specify a seperate end, same as get_node_begin
+		/// @param node Node pointer to get the ending line and column of
+		/// @return const ast::Node::line_col
 		const ast::Node::line_col get_node_end(const ast::NodeCPtr node) const;
 
 		Parser(Parser&&);