diff --git a/.gitignore b/.gitignore index d94c28b..f6c9031 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,6 @@ bin/* compile_commands.json coverage +doc/musique +doc/build +doc/source/api diff --git a/Doxyfile b/Doxyfile index 2c6ff5d..0cf42ea 100644 --- a/Doxyfile +++ b/Doxyfile @@ -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 = +INPUT = src # 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 @@ -943,7 +943,7 @@ FILE_PATTERNS = *.c \ # be searched for input files as well. # The default value is: NO. -RECURSIVE = NO +RECURSIVE = YES # The EXCLUDE tag can be used to specify files and/or directories that should be # excluded from the INPUT source files. This way you can easily exclude a @@ -952,7 +952,7 @@ RECURSIVE = NO # Note that relative paths are relative to the directory from which doxygen is # run. -EXCLUDE = +EXCLUDE = tests # The EXCLUDE_SYMLINKS tag can be used to select whether or not files or # directories that are symbolic links (a Unix file system feature) are excluded diff --git a/Makefile b/Makefile index abce136..1658408 100644 --- a/Makefile +++ b/Makefile @@ -21,6 +21,7 @@ bin/musique: $(Obj) bin/main.o src/*.hh unit-tests: bin/unit-tests ./$< +.PHONY: unit-test-coverage unit-test-coverage: @which gcov >/dev/null || ( echo "[ERROR] gcov is required for test coverage report"; false ) @which gcovr >/dev/null || ( echo "[ERROR] gcovr is required for test coverage report"; false ) @@ -30,6 +31,12 @@ unit-test-coverage: mkdir coverage gcovr -e '.*\.hpp' --html --html-details -o coverage/index.html rm -rf bin + xdg-open coverage/index.html + +.PHONY: doc +doc: Doxyfile src/*.cc src/*.hh + doxygen + cd doc; $(MAKE) html bin/unit-tests: src/tests/*.cc $(Obj) g++ $(CXXFLAGS) $(CPPFLAGS) -o $@ $^ diff --git a/README.md b/README.md index db7b1ad..4e2d6da 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,7 @@ - `make` - Buduje interpreter `bin/musique` - `make clean` - Usuwa reprodukowalne elementy projektu (automatycznie stworzone pliki binarne czy raporty) -- `make unit-tests-coverage` - Uruchamia raport pokrycia kodu przez testy jednostkowe +- `make unit-test-coverage` - Uruchamia raport pokrycia kodu przez testy jednostkowe - `make unit-tests` - Uruchamia testy jednostkowe interpretera ## Budowa projektu diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line, and also +# from the environment for the first two. +SPHINXOPTS ?= +SPHINXBUILD ?= sphinx-build +SOURCEDIR = source +BUILDDIR = build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100644 index 0000000..2050ae8 --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,55 @@ +# This file only contains a selection of the most common options. For a full +# list see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- + +project = 'Musique' +copyright = '2022, Robert Bendun' +author = 'Robert Bendun' + +# -- General configuration --------------------------------------------------- + +extensions = [ + "sphinx_rtd_theme", + "breathe", + "recommonmark", + "exhale" +] + +breathe_projects = { + "musique": "../build/doxygen/xml" +} + +breathe_default_project = "musique" + +exhale_args = { + "containmentFolder": "./api", + "rootFileName": "musique-root.rst", + "createTreeView": True, + "doxygenStripFromPath": ".." +} + +primary_domain = "cpp" +highlight_language = "cpp" + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = [] + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 0000000..c996a03 --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,22 @@ +.. Musique documentation master file, created by + sphinx-quickstart on Sun May 8 17:37:28 2022. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to Musique's documentation! +=================================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + api/musique-root + + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/src/location.cc b/src/location.cc index 03292a9..122990b 100644 --- a/src/location.cc +++ b/src/location.cc @@ -1,6 +1,14 @@ #include -Location Location::advance(u32 rune) +Location Location::at(usize line, usize column) +{ + Location loc; + loc.line = line; + loc.column = column; + return loc; +} + +Location& Location::advance(u32 rune) { switch (rune) { case '\n': diff --git a/src/musique.hh b/src/musique.hh index 732e629..059e0f5 100644 --- a/src/musique.hh +++ b/src/musique.hh @@ -46,22 +46,27 @@ namespace errors }; } +/// \brief Location describes code position in `file line column` format. +/// It's used both to represent position in source files provided +// to interpreter and internal interpreter usage. struct Location { - std::string_view filename = ""; - usize line = 1, column = 1; + std::string_view filename = ""; ///< File that location is pointing to + usize line = 1; ///< Line number (1 based) that location is pointing to + usize column = 1; ///< Column number (1 based) that location is pointing to - Location advance(u32 rune); + /// Advances line and column numbers based on provided rune + /// + /// If rune is newline, then column is reset to 1, and line number is incremented. + /// Otherwise column number is incremented. + /// + /// @param rune Rune from which column and line numbers advancements are made. + Location& advance(u32 rune); bool operator==(Location const& rhs) const = default; - static Location at(usize line, usize column) - { - Location loc; - loc.line = line; - loc.column = column; - return loc; - } + //! Creates location at default filename with specified line and column number + static Location at(usize line, usize column); // Used to describe location of function call in interpreter (internal use only) #if defined(__cpp_lib_source_location) @@ -70,6 +75,13 @@ struct Location static Location caller(char const* file = __builtin_FILE(), usize line = __builtin_LINE()); #else #error Cannot implement Location::caller function + /// Returns location of call in interpreter source code. + /// + /// Example of reporting where `foo()` was beeing called: + /// @code + /// void foo(Location loc = Location::caller()) { std::cout << loc << '\n'; } + /// @endcode + static Location caller(); #endif };