Documentation for programmers

This commit is contained in:
Robert Bendun 2022-05-29 01:00:13 +02:00
parent 26521be98d
commit 563786312c
4 changed files with 63 additions and 10 deletions

View File

@ -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.

View File

@ -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

View File

@ -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

55
doc/index.md Normal file
View File

@ -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.