commit 5f72a33625e084611a42a222cfb4729f591e50f8
parent 5eeeabb0889761d1ec328bfd54effa08d892494d
Author: Morel Bérenger <berengermorel76@gmail.com>
Date: Mon, 30 Nov 2020 12:19:08 +0100
improve in-source documentation
* adds comments on top of files to explain the file's goal
* fix a truncated? comment
Diffstat:
6 files changed, 55 insertions(+), 4 deletions(-)
diff --git a/btl/src/memory.hpp b/btl/src/memory.hpp
@@ -16,6 +16,11 @@
// misrepresented as being the original software.
// 3. This notice may not be removed or altered from any source distribution.
+// This file defines unique_res and weak_res class utilities.
+// goal: easy RAII for any resource, without any assumption
+// about what is an invalid value, and without consuming
+// more data memory than a single, raw pointer.
+
#ifndef MEMORY_HPP
#define MEMORY_HPP
diff --git a/btl/src/optparser.cpp b/btl/src/optparser.cpp
@@ -16,6 +16,8 @@
// misrepresented as being the original software.
// 3. This notice may not be removed or altered from any source distribution.
+// option parser: implementation
+
#include <string.h>
#include <assert.h>
#include <stdlib.h>
diff --git a/btl/src/optparser.hpp b/btl/src/optparser.hpp
@@ -16,6 +16,18 @@
// misrepresented as being the original software.
// 3. This notice may not be removed or altered from any source distribution.
+// this file contains the definitions of structures and
+// functions to parse command-line options, with some C++
+// helpers (because templates rocks and C does not have
+// them).
+// C++ *should not* be required to use the core
+// functionnality, but actual C uses have not been tested:
+// you've been warned.
+// Other functions are planned to parse data from sources
+// different than argv, like getenv() or a configuration
+// file.
+// That's still on the TODO-list, though.
+
#ifndef OPTPARSER_HPP
#define OPTPARSER_HPP
diff --git a/btl/src/string.hpp b/btl/src/string.hpp
@@ -16,6 +16,19 @@
// misrepresented as being the original software.
// 3. This notice may not be removed or altered from any source distribution.
+// this file defines a set of operators and helpers to use
+// vector's data as a string, which means allowing the use
+// of SL's algorithms in a less surprising way than
+// std::string.
+// It's really only contains a typedef, plus functions for
+// concatenation, string creation and conversion.
+// Other features I think really necessaryare *already* in
+// vector or algorithm, anyway.
+// Be warned that this container still sucks, and still do
+// not handle strings which contains characters of various
+// size like UTF-8 (for that, a proper container without
+// random access would be needed).
+
#ifndef STRING_HPP
#define STRING_HPP
diff --git a/btl/src/utils.hpp b/btl/src/utils.hpp
@@ -16,6 +16,9 @@
// misrepresented as being the original software.
// 3. This notice may not be removed or altered from any source distribution.
+// This files contains various utilities and macros, some
+// useful, some useless, some harmful.
+
#ifndef UTILS_HPP
#define UTILS_HPP
@@ -38,7 +41,7 @@
#define BUG_CHECK( cond, err ) if( cond ) return err
#endif
-//display a system error with an optional
+//display a system error
#define syserr( str ) \
do { \
fputs( HEADER_LOG ": ", stderr ); \
@@ -46,10 +49,11 @@
fputs( ": " str "\n", stderr ); \
} while( 0 )
-//ok, this should not be here, since not related to any logging stuff
-//otoh, I think this file should be renamed utils, or alike...
-//it's only defines anyway...
+// C++ malloc, because casting from malloc is annoying and
+// new does not just allocates (it constructs, too).
#define ALLOC( type ) static_cast<type*>( malloc( sizeof( type ) ) )
+// tired of looooong lines of code because casting and
+// dereferencing? This saves 6 out of 11 characters per use.
#define REDEF( type, dst, src ) type& dst = *static_cast<type*>( src )
//simply check if an array is nullptr or starts with a value considered invalid
diff --git a/btl/src/vector.hpp b/btl/src/vector.hpp
@@ -16,6 +16,21 @@
// misrepresented as being the original software.
// 3. This notice may not be removed or altered from any source distribution.
+// a partial vector implementation.
+// Why use it? Because:
+// * it does *not* rely on exceptions;
+// * it does *not* requires special tooling for debugging;
+// * it allows lot smaller final binaries (than STL);
+// You can just include it, and not use it by defining the
+// WITH_STL flag: handy when you want STL for production,
+// but this one for debugging.
+//
+// NOTE: the API is *not* 100% compatible, since it does not
+// uses exceptions, but return values to signal errors, and
+// is incomplete.
+// Also, methods which are *not* in std::vector will be
+// exposed in the end, to help handling memory.
+
#ifndef VECTOR_HPP
#define VECTOR_HPP
