add initial doxygen documentation infra

.gitignore

@@ -1,7 +1,7 @@
-subprojects/libostd
 *.o
 *.core
 *.so
 build/
 .idea/
 .vscode/
+doc/output

doc/main_page.md

@@ -0,0 +1,107 @@
+# Libcubescript Documentation {#index}
+
+## What is Cubescript?
+
+ubescript is a minimal scripting language first introduced in the Cube FPS
+and carried over into derived games and game engines such as Sauerbraten.
+Originally being little more than a few hundred lines of code, serving
+primarily as the console and configuration file format of the game, it
+grew more advanced features as well as a bytecode VM.
+
+Nowadays, it is a minimal but relatively fully featured scripting language
+based around the concept that everything can be interpreted as a string.
+It excels at its original purpose as well as things like text preprocessing.
+It comes with a Lisp-like syntax and a variety of standard library functions.
+
+## What is Libcubescript?
+
+Libcubescript is a project that aims to provide an independent, improved,
+separate implementation of the language, available as a library, intended to
+satisfy the needs of the OctaForge project. It was originally forked from
+Cubescript as present in the Tesseract game/engine and gradually rewritten;
+right now, very little of the original code remains. At language level it is
+mostly compatible with the other implementations (although with a stricter
+parser and extra features), while the standard library does not aim to be
+fully compatible. Some features are also left up to the user to customize,
+so that it is not tied to game engines feature-wise.
+
+Like the codebase it is derived from, it is available under the permissive
+zlib license, and therefore compatible with just about anything.
+
+## Benefits and differences
+
+There's a variety of things that set this implementation apart:
+
+* It's independent and can be embedded in any project
+* There is no global state, so you can have as many Cubescripts as you want,
+  in one program
+* Written in C++20, following modern language conventions, both internally
+  and at API level
+* That means the ability to use lambdas as commands, including captures,
+  type inference and so on
+* There is a robust allocator system in place, and all memory the library
+  uses is allocated through it; that gives you complete control over its
+  memory (for tracking, sandboxing, limits, etc.)
+* A large degree of memory safety, with no manual management
+* Strings are interned, with a single reference counted instance of any
+  string existing at a time, which lowers memory usage and simplifies its
+  management
+* Minimal stack memory usage, which means no artificial limits on recursion
+  depth as well as safe usage from threads and coroutines with small stacks
+* Errors will no longer cause the interpreter to march on, instead acting
+  like real errors
+* Protected calls allow you to catch errors in a similar way to exceptions,
+  and nearly every error can be caught
+* Stricter parsing, with things like unfinished strings being caught
+* Loops now have `break` and `continue` statements
+* Customizable integer and floating point types
+* Full support for symbol visibility in API
+* Highly portable and cross-platform, no dependencies other than a compiler
+* Clean codebase that is easy to pick up and contribute to
+
+## Building and usage
+
+The library has absolutely no dependencies other than a C++20 compiler,
+similarly there are no dependencies on system or architecture specific
+things, so it should work on any OS and any CPU.
+
+The C++20 support does not have to be complete. These are the baselines
+(which are ensured by the CI):
+
+* GCC 10
+* Clang 10 (with libstdc++ or libc++)
+* Microsoft Visual C++ 2019
+
+Older versions of either of these are known not to work.
+
+You will need [Meson](https://mesonbuild.com/) to build the project. Most
+Unix-like systems have it in their package management, on Windows there is
+an installer available on their website. Being written in Python, you can
+also use `pip` to get an up to date version on any OS.
+
+Once you have it, compiling is simple, e.g. on Unix-likes you can do:
+
+~~~
+mkdir build && cd build
+meson ..
+ninja all
+~~~
+
+Refer to Meson's manual for how to customize whether you want a shared or
+static library and so on. By default, you will get a shared library plus
+a REPL (interactive interpreter). The REPL also serves as an example of
+how to use the API.
+
+If you don't want the REPL, use `-Drepl=disabled`. When compiled, it can
+have support for line editing and command history. This is provided through
+`linenoise` (which is a minimal single-file line editing library bundled
+with the project, and is the default). In case you're on a platform that
+`linenoise` does not support (highly unlikely), there is a fallback without
+any line editing as well. Pass `-Dlinenoise=disabled` to use the fallback.
+
+The version of `linenoise` bundled with the project is `cpp-linenoise`, available
+at https://github.com/yhirose/cpp-linenoise. Our version is modified, so that
+it builds cleanly with our flags, and so that it supports the "hints" feature
+available in original `linenoise`. Other than the modifications, it is baseed
+on upstream git revision `a927043cdd5bfe203560802e56a7e7ed43156ed3`. The reason
+we use this instead of upstream `linenoise` is Windows support.

include/cubescript/cubescript.hh

@@ -1,3 +1,13 @@
+/** @file cubescript.hh
+ *
+ * @brief The main include file for the library.
+ *
+ * Include this file (like `#include <cubescript/cubescript.hh>`) to access
+ * the API. You should generally not include the individual sub-files.
+ *
+ * @copyright See COPYING.md in the project tree for further information.
+ */
+ 
 #ifndef LIBCUBESCRIPT_CUBESCRIPT_HH
 #define LIBCUBESCRIPT_CUBESCRIPT_HH
 

include/cubescript/cubescript/callable.hh

@@ -1,3 +1,12 @@
+/** @file callable.hh
+ *
+ * @brief Internal callable data structure.
+ *
+ * There is no public API in this file.
+ *
+ * @copyright See COPYING.md in the project tree for further information.
+ */
+
 #ifndef LIBCUBESCRIPT_CUBESCRIPT_CALLABLE_HH
 #define LIBCUBESCRIPT_CUBESCRIPT_CALLABLE_HH
 
@@ -10,6 +19,7 @@
 namespace cubescript {
 namespace internal {
 
+/** @private */
 template<typename R, typename ...A>
 struct callable {
 private:

include/cubescript/cubescript/error.hh

@@ -1,3 +1,12 @@
+/** @file error.hh
+ *
+ * @brief Error handling API.
+ *
+ * Defines structures and methods used for error handling in the library.
+ *
+ * @copyright See COPYING.md in the project tree for further information.
+ */
+
 #ifndef LIBCUBESCRIPT_CUBESCRIPT_ERROR_HH
 #define LIBCUBESCRIPT_CUBESCRIPT_ERROR_HH
 

include/cubescript/cubescript/ident.hh

@@ -1,3 +1,14 @@
+/** @file ident.hh
+ *
+ * @brief Identifier management.
+ *
+ * Identifiers in `libcubescript` represent variables, aliases, commands
+ * and so on. This file contains the handles for those and everything you
+ * need to interface with them.
+ *
+ * @copyright See COPYING.md in the project tree for further information.
+ */
+
 #ifndef LIBCUBESCRIPT_CUBESCRIPT_IDENT_HH
 #define LIBCUBESCRIPT_CUBESCRIPT_IDENT_HH
 

include/cubescript/cubescript/platform.hh

@@ -1,8 +1,50 @@
+/** @file platform.hh
+ *
+ * @brief Utility macros and platform abstraction.
+ *
+ * Defines utility macros that you are not supposed to use yourself.
+ *
+ * @copyright See COPYING.md in the project tree for further information.
+ */
+
 #ifndef LIBCUBESCRIPT_CUBESCRIPT_PLATFORM_HH
 #define LIBCUBESCRIPT_CUBESCRIPT_PLATFORM_HH
 
 namespace cubescript {
 
+#ifdef LIBCS_GENERATING_DOC
+
+/** @brief Public API tag.
+ *
+ * All public API of the library is tagged like this.
+ *
+ * On Windows, the behavior of this is conditional. If `LIBCUBESCRIPT_DLL` is
+ * not defined, it expands to no value (that means we're either building or
+ * using a static library). If it is defined, it will tag the API with either
+ * `dllexport` (when building the lib, defined with `LIBCUBESCRIPT_BUILD`)
+ * or `dllimport` (when using the lib).
+ *
+ * On Unix-like systems with GCC-style compilers, this will mark the API as
+ * externally visible. The library is by default built so that symbols are
+ * normally hidden, so any external API needs to be tagged.
+ *
+ * @see LIBCUBESCRIPT_LOCAL
+ */
+#define LIBCUBESCRIPT_EXPORT
+
+/** @brief Private API tag.
+ *
+ * Since symbols are private by default, this usually has no purpose. However,
+ * when marking entire structures exported, this affects all methods inside;
+ * in those cases this can be used to mark specific methods as for use only
+ * inside of the library (private methods not called in any public header).
+ *
+ * @see LIBCUBESCRIPT_EXPORT
+ */
+#define LIBCUBESCRIPT_LOCAL
+
+#else
+
 #if defined(__CYGWIN__) || (defined(_WIN32) && !defined(_XBOX_VER))
 #  ifdef LIBCUBESCRIPT_DLL
 #    ifdef LIBCUBESCRIPT_BUILD
@@ -24,6 +66,8 @@ namespace cubescript {
 #  endif
 #endif
 
+#endif /* LIBCS_GENERATING_DOC */
+
 } /* namespace cubescript */
 
 #endif /* LIBCUBESCRIPT_CUBESCRIPT_PLATFORM_HH */

include/cubescript/cubescript/state.hh

@@ -1,3 +1,13 @@
+/** @file state.hh
+ *
+ * @brief State API.
+ *
+ * The state is the main handle using which you interact with the language
+ * from C++. It represents a single Cubescript thread.
+ *
+ * @copyright See COPYING.md in the project tree for further information.
+ */
+
 #ifndef LIBCUBESCRIPT_CUBESCRIPT_STATE_HH
 #define LIBCUBESCRIPT_CUBESCRIPT_STATE_HH
 

include/cubescript/cubescript/util.hh

@@ -1,3 +1,14 @@
+/** @file util.hh
+ *
+ * @brief Utility API.
+ *
+ * This contains various utilities that don't quite fit within the other
+ * structures, but provide convenience; this includes things such as parsing
+ * of lists, strings and numbers.
+ *
+ * @copyright See COPYING.md in the project tree for further information.
+ */
+
 #ifndef LIBCUBESCRIPT_CUBESCRIPT_UTIL_HH
 #define LIBCUBESCRIPT_CUBESCRIPT_UTIL_HH
 

include/cubescript/cubescript/value.hh

@@ -1,3 +1,15 @@
+/** @file value.hh
+ *
+ * @brief Value API.
+ *
+ * This file contains value handles. These include the main value handle,
+ * which represents any Cubescript value as a tagged union (and you use it
+ * for handling of things such as command arguments and return values), as
+ * well as string references and bytecode references.
+ *
+ * @copyright See COPYING.md in the project tree for further information.
+ */
+
 #ifndef LIBCUBESCRIPT_CUBESCRIPT_VALUE_HH
 #define LIBCUBESCRIPT_CUBESCRIPT_VALUE_HH
 

include/cubescript/cubescript_conf.hh

@@ -1,14 +1,89 @@
+/** @file cubescript_conf.hh
+ *
+ * @brief Library configuration.
+ *
+ * This is the one file you are allowed to touch as a user - it contains
+ * settings that are used when building the library, notably the integer
+ * and floating point types used and their formats (used for conversions).
+ *
+ * Usually you will not want to touch this, but occasionally you might want
+ * to, e.g. to make a build of the library that uses double precision floats
+ * or larger integers.
+ *
+ * @copyright See COPYING.md in the project tree for further information.
+ */
+
 #ifndef LIBCUBESCRIPT_CUBESCRIPT_CONF_HH
 #define LIBCUBESCRIPT_CUBESCRIPT_CONF_HH
 
 #include <type_traits>
 
 namespace cubescript {
+    /** @brief The integer type used.
+     *
+     * While Cubescript is a stringly typed language, it uses integers and
+     * floats internally in a transparent manner where possible, and allows
+     * you to retrieve and pass integers and floats in commands and so on.
+     *
+     * This is the integer type used. By default, it's `int`, which is a
+     * 32-bit signed integer on most platforms. Keep in mind that is is
+     * necessary for this type to be a signed integer type.
+     *
+     * @see float_type
+     * @see INTEGER_FORMAT
+     */
     using integer_type = int;
+
+    /** @brief The floating point type used.
+     *
+     * By default, this is `float`, which is on most platforms an IEEE754
+     * binary32 data type.
+     *
+     * @see integer_type
+     * @see FLOAT_FORMAT
+     * @see ROUND_FLOAT_FORMAT
+     */
     using float_type = float;
 
+    /** @brief The integer format used.
+     *
+     * This is a formatting specifier as in `printf`, corresponding to the
+     * `integer_type` used. It is used to handle conversions from the type
+     * to strings, as well as in the default integer variable handler when
+     * printing.
+     *
+     * There are no special restrictions imposed on the floating point type
+     * other than that it actually has to be floating point.
+     *
+     * @see integer_type
+     * @see FLOAT_FORMAT
+     */
     constexpr auto const INTEGER_FORMAT = "%d";
+
+    /** @brief The float format used.
+     *
+     * This is a formatting specifier as in `printf`, corresponding to the
+     * `float_type` used. It is used to handle conversions from the type to
+     * strings, as well as in the default float variable handler when printing.
+     *
+     * When the floating point value is equivalent to its integer value (i.e.
+     * it has no decimal point), ROUND_FLOAT_FORMAT is used.
+     *
+     * @see float_type
+     * @see ROUND_FLOAT_FORMAT
+     * @see INTEGER_FORMAT
+     */
     constexpr auto const FLOAT_FORMAT = "%.7g";
+
+    /** @brief The round float format used.
+     *
+     * This is a formatting specifier as in `printf`, corresponding to the
+     * `float_type` used. It's like `FLOAT_FORMAT` but used when the value
+     * has no decimal point.
+     *
+     * @see float_type
+     * @see FLOAT_FORMAT
+     */
     constexpr auto const ROUND_FLOAT_FORMAT = "%.1f";
 } /* namespace cubescript */