Much documentation (I consider it to be quite complete)

1 files changed, 40 insertions, 0 deletions

diff --git a/src/cppc4group.hpp b/src/cppc4group.hpp
index 166fadf..a1bb28a 100644
--- a/src/cppc4group.hpp
+++ b/src/cppc4group.hpp
@@ -1,5 +1,14 @@
 #pragma once
 
+// this is the main and only include file for cppc4group, the C++-wrapper for cc4group
+// because cc4group is already object-oriented, this is just a simple wrapper and almost all methods work exactly the same, just with C++-types
+// although, when dealing with raw memory (because cc4group can't know the type of the stored data) also users of this wrapper have to deal with some void*
+// because most methods behave exactly the same, please look at cc4group.h for their description (they are named exactly the same with a few exceptions)
+// in case their are real differences, they will be noted in this header also
+// until now, all examples only use cc4group's C-API, but as a C++-programmer you should have no problems reading them anyway
+// one general difference to the C-API that is not mentioned at the individual methods is that functions actually returning data return an std::optional instead of a bool...
+// ...the optional will be populated normally and empty in error cases
+
 #include <memory>
 #include <vector>
 #include <optional>
@@ -7,19 +16,27 @@
 #include <functional>
 
 class CppC4Group {
+	// all C-related stuff is hidden from this header so it doesn't land in the precious C++-only code this might be used in...
+	// ...and pollute the root-namespace with various types that are better contained in this class instead
 	struct Private;
 
 	std::unique_ptr<Private> p;
 
 public:
+	// this struct is used for the getEntryData-method to return them in a uniform way (instead of using reference- or pointer-arguments)
 	struct Data {
+		// this will contain the information cc4group.getEntryData stores in its data argument
 		const void* data;
+		// and the same for size
 		size_t size;
 
+		// there should be no reason to construct one of these as API user, but it is needed internally
 		Data();
 		Data(const void* const data, const size_t size);
 	};
 
+	// this struct contains the same things as the CC4Group_EntryInfo struct of the C-version
+	// member descriptions also apply equally here
 	struct EntryInfo {
 		std::string fileName;
 		int32_t modified;
@@ -31,21 +48,36 @@ public:
 		bool official;
 	};
 
+	// this struct is used in custom tmp memory strategies
+	// instead of using additional pointer arguments to return the cleanup stuff everything is returned in a single one of this by the tmp memory strategy function
 	struct TmpMemory {
 		using TmpMemoryCleanupCallback = std::function<bool(void* memory, void* arg)>;
 
+		// memory needs to hold the readily allocated memory
+		// it corresponds to the pointer that needs to be returned by C tmp memory strategies
 		void* memory;
+
+		// cleanup is a fancy std::function that will be called when the memory is not needed anymore
+		// it receives the memory pointer stored above and the custom argument stored right below as arguments
 		TmpMemoryCleanupCallback cleanup;
+
+		// this can be set to arbitrary data needed by the cleanup callback to properly cleanup all used resources
 		void* arg;
 
+		// this is just a plain constructor setting each member accordingly
 		TmpMemory(void* const memory, const TmpMemoryCleanupCallback& cleanup, void* const arg);
 	};
 
 public:
+	// the C++ custom tmp memory strategy only receives the needed size as argument and must return an optional containing the information described above (TmpMemory)
+	// or an empty optional on failure
 	using TmpMemoryCallback = std::optional<TmpMemory>(*)(size_t size);
+
+	// these two are equivalent to their C counterparts
 	using ReadCallback = bool(*)(const void** const data, size_t* const size, void* const arg);
 	using SetupCallback = bool(*)(void* const arg);
 
+	// these enums are just mapped to their C-counterparts internally
 	enum TmpMemoryStrategy {
 		Memory,
 		File,
@@ -58,11 +90,17 @@ public:
 		Reference
 	};
 
+	// use this to set one of the predefined strategies
 	static void setTmpMemoryStrategy(const TmpMemoryStrategy strategy);
+
+	// and this for your own custom strategy
 	static void setTmpMemoryStrategy(const TmpMemoryCallback callback);
 
 public:
+	// the constructor will automatically construct an internal CC4Group, so no new-equivalent method is needed
 	CppC4Group();
+
+	// the destructor will automatically delete the internal CC4Group, so also no extra method needed
 	~CppC4Group();
 
 	void create();
@@ -71,6 +109,8 @@ public:
 	bool openFilePointer(FILE* file);
 	bool openMemory(const void* const data, const size_t size, const MemoryManagement management = Reference);
 	bool openWithReadCallback(const ReadCallback callback, void* const callbackArg, const MemoryManagement management = Take, SetupCallback initCallback = nullptr, SetupCallback deinitCallback = nullptr);
+
+	// save actually maps to both cc4group.save and cc4group.saveOverwrite, thanks to default arguments (yes, thats the reason why they are separate in the C-API)
 	bool save(const std::string& path, const bool overwrite = false);
 
 	bool extractAll(const std::string& path);