From 563786312c4b6fb9e65f83fa13a75b9a9eeee5cd Mon Sep 17 00:00:00 2001
From: Robert Bendun <robben@st.amu.edu.pl>
Date: Sun, 29 May 2022 01:00:13 +0200
Subject: [PATCH] Documentation for programmers

---
 Doxyfile     | 14 ++++++-------
 Makefile     |  1 -
 README.md    |  3 +--
 doc/index.md | 55 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 4 files changed, 63 insertions(+), 10 deletions(-)
 create mode 100644 doc/index.md

diff --git a/Doxyfile b/Doxyfile
index 0cf42ea..c839c2a 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -58,7 +58,7 @@ PROJECT_LOGO           =
 # entered, it will be relative to the location where doxygen was started. If
 # left blank the current directory will be used.
 
-OUTPUT_DIRECTORY       = doc/build/doxygen/
+OUTPUT_DIRECTORY       = doc/build/
 
 # If the CREATE_SUBDIRS tag is set to YES then doxygen will create 4096 sub-
 # directories (in 2 levels) under the output directory of each output format and
@@ -485,13 +485,13 @@ NUM_PROC_THREADS       = 1
 # normally produced when WARNINGS is set to YES.
 # The default value is: NO.
 
-EXTRACT_ALL            = NO
+EXTRACT_ALL            = YES
 
 # If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will
 # be included in the documentation.
 # The default value is: NO.
 
-EXTRACT_PRIVATE        = NO
+EXTRACT_PRIVATE        = YES
 
 # If the EXTRACT_PRIV_VIRTUAL tag is set to YES, documented private virtual
 # methods of a class will be included in the documentation.
@@ -864,7 +864,7 @@ WARN_LOGFILE           =
 # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING
 # Note: If this tag is empty the current directory is searched.
 
-INPUT                  = src
+INPUT                  = src doc/index.md
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -1061,7 +1061,7 @@ FILTER_SOURCE_PATTERNS =
 # (index.html). This can be useful if you have a project on for instance GitHub
 # and want to reuse the introduction page also for the doxygen output.
 
-USE_MDFILE_AS_MAINPAGE =
+USE_MDFILE_AS_MAINPAGE = doc/index.md
 
 #---------------------------------------------------------------------------
 # Configuration options related to source browsing
@@ -1213,7 +1213,7 @@ IGNORE_PREFIX          =
 # If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output
 # The default value is: YES.
 
-GENERATE_HTML          = NO
+GENERATE_HTML          = YES
 
 # The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
@@ -1582,7 +1582,7 @@ DISABLE_INDEX          = NO
 # The default value is: NO.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-GENERATE_TREEVIEW      = NO
+GENERATE_TREEVIEW      = YES
 
 # The ENUM_VALUES_PER_LINE tag can be used to set the number of enum values that
 # doxygen will group on one line in the generated HTML documentation.
diff --git a/Makefile b/Makefile
index 101ba8c..fd98db9 100644
--- a/Makefile
+++ b/Makefile
@@ -75,7 +75,6 @@ unit-test-coverage:
 
 doc: Doxyfile src/*.cc src/*.hh
 	doxygen
-	cd doc; $(MAKE) html
 
 doc-open: doc
 	xdg-open ./doc/build/html/index.html
diff --git a/README.md b/README.md
index d2a905e..05240b5 100644
--- a/README.md
+++ b/README.md
@@ -50,8 +50,7 @@ $ make bin/musique
 ├── bin            Miejsce produkcji plików wykonywalnych
 ├── coverage
 ├── doc            Dokumentacja języka, interpretera
-│   ├── build      Miejsce produkcji dokumentacji
-│   └── source     Źródła dokumentacji Sphinx
+│   └── build      Miejsce produkcji dokumentacji
 ├── etc/tools      Dodatkowe narzędzia
 ├── lib            Zewnętrzne zależności projektu
 │   ├── expected
diff --git a/doc/index.md b/doc/index.md
new file mode 100644
index 0000000..92611b8
--- /dev/null
+++ b/doc/index.md
@@ -0,0 +1,55 @@
+# Musique interpreter documentation
+
+This documentation system contains information for programmers that will like to contribute or learn about Musique interpreter (and [REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop)).
+
+## Building
+
+To build you need to have installed:
+
+- Modern C++ compiler compatible with GNU compund expression extension and C++20 support;
+- Following libraries when targetting GNU/Linux: `libreadline`, `libasound`.
+
+Then all you have to do is run `make` in main source directory.
+
+## Using interpreter as a library
+
+Interpreter usage consist of three steps:
+
+- creating chosen MIDI support for an Interpreter
+- creating Interpreter instance
+- parsing and evaluating source code
+
+Parsing and evaluating may result in an error. For this case Result type offers `error()` method to get produced error and `has_value()` to check if computation was successfull.
+
+### Simple example
+
+We define `run` function that will do steps above, to execute provided string.
+
+```cpp
+void run(std::string_view source)
+{
+	Interpreter interpreter;
+
+	// We don't want midi support so we ignore it
+	interpreter.midi_connection = nullptr;
+
+	// We set filename used in error reporting to "example"
+	auto ast = Parser::parse(source, "example");
+
+	// Check if file was properly parsed. If not print error message and exit
+	if (!ast.has_value()) {
+		std::cerr << ast.error() << '\n';
+		return;
+	}
+
+	// Evaluate program
+	auto result = interpreter.eval(std::move(ast));
+	if (result.has_value()) {
+		std::cout << *result << std::endl;
+	} else {
+		std::cerr << result.error() << '\n';
+	}
+}
+```
+
+When in doubt see `src/main.cc` as example on library usage.