#159 Fully annotate all methods (#164)

Fixed #159
cmannett85 · Jan 31, 2021 · 6a3fa27 · 6a3fa27
1 parent 0b01ecb
commit 6a3fa27
Show file tree

Hide file tree

Showing 34 changed files with 295 additions and 172 deletions.
diff --git a/.github/workflows/docs_pusher.yml b/.github/workflows/docs_pusher.yml
@@ -24,13 +24,16 @@ jobs:
       with:
         fetch-depth: 0
 
+    # Due to https://github.com/doxygen/doxygen/issues/7411, we have to use
+    # Doxygen 1.8.18
     - name: Update packages
       run: |
         wget http://mirrors.kernel.org/ubuntu/pool/universe/l/lcov/lcov_1.14-2_all.deb
         wget http://mirrors.kernel.org/ubuntu/pool/main/b/boost1.71/libboost1.71-dev_1.71.0-6ubuntu6_amd64.deb
         wget http://mirrors.kernel.org/ubuntu/pool/universe/b/boost1.71/libboost-test1.71-dev_1.71.0-6ubuntu6_amd64.deb
         wget http://mirrors.kernel.org/ubuntu/pool/universe/b/boost1.71/libboost-test1.71.0_1.71.0-6ubuntu6_amd64.deb
-        sudo apt install doxygen graphviz ./libboost1.71-dev_1.71.0-6ubuntu6_amd64.deb ./libboost-test1.71.0_1.71.0-6ubuntu6_amd64.deb ./libboost-test1.71-dev_1.71.0-6ubuntu6_amd64.deb ./lcov_1.14-2_all.deb
+        wget http://mirrors.kernel.org/ubuntu/pool/universe/d/doxygen/doxygen_1.8.18-1ubuntu3_amd64.deb
+        sudo apt install ./doxygen_1.8.18-1ubuntu3_amd64.deb graphviz ./libboost1.71-dev_1.71.0-6ubuntu6_amd64.deb ./libboost-test1.71.0_1.71.0-6ubuntu6_amd64.deb ./libboost-test1.71-dev_1.71.0-6ubuntu6_amd64.deb ./lcov_1.14-2_all.deb
 
     - name: Generate API documentation
       run: |

diff --git a/.github/workflows/pr_checker.yml b/.github/workflows/pr_checker.yml
@@ -133,9 +133,12 @@ jobs:
       with:
         fetch-depth: 1
 
+    # Due to https://github.com/doxygen/doxygen/issues/7411, we have to use
+    # Doxygen 1.8.18
     - name: Update packages
       run: |
-        sudo apt install doxygen graphviz
+        wget http://mirrors.kernel.org/ubuntu/pool/universe/d/doxygen/doxygen_1.8.18-1ubuntu3_amd64.deb
+        sudo apt install ./doxygen_1.8.18-1ubuntu3_amd64.deb graphviz
 
     - name: Generate API documentation
       run: |
@@ -158,7 +161,8 @@ jobs:
         wget http://mirrors.kernel.org/ubuntu/pool/main/b/boost1.71/libboost1.71-dev_1.71.0-6ubuntu6_amd64.deb
         wget http://mirrors.kernel.org/ubuntu/pool/universe/b/boost1.71/libboost-test1.71-dev_1.71.0-6ubuntu6_amd64.deb
         wget http://mirrors.kernel.org/ubuntu/pool/universe/b/boost1.71/libboost-test1.71.0_1.71.0-6ubuntu6_amd64.deb
-        sudo apt install doxygen graphviz g++-10 ./libboost1.71-dev_1.71.0-6ubuntu6_amd64.deb ./libboost-test1.71.0_1.71.0-6ubuntu6_amd64.deb ./libboost-test1.71-dev_1.71.0-6ubuntu6_amd64.deb
+        wget http://mirrors.kernel.org/ubuntu/pool/universe/d/doxygen/doxygen_1.8.18-1ubuntu3_amd64.deb
+        sudo apt install ./doxygen_1.8.18-1ubuntu3_amd64.deb graphviz g++-10 ./libboost1.71-dev_1.71.0-6ubuntu6_amd64.deb ./libboost-test1.71.0_1.71.0-6ubuntu6_amd64.deb ./libboost-test1.71-dev_1.71.0-6ubuntu6_amd64.deb
 
     - name: Build
       run: |

diff --git a/.github/workflows/release_builder.yml b/.github/workflows/release_builder.yml
@@ -30,12 +30,15 @@ jobs:
         MSG="${MSG//$'\r'/'%0D'}"
         echo "::set-output name=commit_msg::${MSG}"
 
+    # Due to https://github.com/doxygen/doxygen/issues/7411, we have to use
+    # Doxygen 1.8.18
     - name: Update packages
       run: |
         wget http://mirrors.kernel.org/ubuntu/pool/main/b/boost1.71/libboost1.71-dev_1.71.0-6ubuntu6_amd64.deb
         wget http://mirrors.kernel.org/ubuntu/pool/universe/b/boost1.71/libboost-test1.71-dev_1.71.0-6ubuntu6_amd64.deb
         wget http://mirrors.kernel.org/ubuntu/pool/universe/b/boost1.71/libboost-test1.71.0_1.71.0-6ubuntu6_amd64.deb
-        sudo apt install doxygen graphviz g++-10 ./libboost1.71-dev_1.71.0-6ubuntu6_amd64.deb ./libboost-test1.71.0_1.71.0-6ubuntu6_amd64.deb ./libboost-test1.71-dev_1.71.0-6ubuntu6_amd64.deb
+        wget http://mirrors.kernel.org/ubuntu/pool/universe/d/doxygen/doxygen_1.8.18-1ubuntu3_amd64.deb
+        sudo apt install ./doxygen_1.8.18-1ubuntu3_amd64.deb graphviz g++-10 ./libboost1.71-dev_1.71.0-6ubuntu6_amd64.deb ./libboost-test1.71.0_1.71.0-6ubuntu6_amd64.deb ./libboost-test1.71-dev_1.71.0-6ubuntu6_amd64.deb
 
     - name: Build
       id: build

diff --git a/include/malbolge/algorithm/container_ops.hpp b/include/malbolge/algorithm/container_ops.hpp
@@ -22,7 +22,8 @@ namespace algorithm
  * @return True if @a c contains @a value
  */
 template <typename Container, typename Value>
-bool any_of(const Container& c, Value&& value)
+[[nodiscard]]
+constexpr bool any_of(const Container& c, Value&& value)
 {
     using std::begin;
     using std::end;
@@ -40,7 +41,9 @@ bool any_of(const Container& c, Value&& value)
  * @return True if @a c contains any value in @a value_container
  */
 template <typename Container, typename ValueContainer>
-bool any_of_container(const Container& c, ValueContainer&& value_container)
+[[nodiscard]]
+constexpr bool any_of_container(const Container& c,
+                                const ValueContainer& value_container)
 {
     using std::begin;
     using std::end;

diff --git a/include/malbolge/algorithm/remove_from_range.hpp b/include/malbolge/algorithm/remove_from_range.hpp
@@ -21,7 +21,7 @@ namespace algorithm
  * @return The updated @a last
  */
 template <typename ForwardIt>
-ForwardIt remove_from_range(ForwardIt it, ForwardIt last)
+constexpr ForwardIt remove_from_range(ForwardIt it, ForwardIt last)
 {
     auto first = it;
     return std::move(++first, last, it);

diff --git a/include/malbolge/algorithm/trim.hpp b/include/malbolge/algorithm/trim.hpp
@@ -25,7 +25,7 @@ namespace algorithm
  * @param p Predicate instance
  */
 template <typename Iter, typename Predicate>
-void trim_left(Iter& begin, Iter end, Predicate&& p)
+constexpr void trim_left(Iter& begin, Iter end, Predicate p)
 {
     for ( ; begin != end; ++begin) {
         if (!p(*begin)) {
@@ -48,7 +48,7 @@ void trim_left(Iter& begin, Iter end, Predicate&& p)
  * @param p Predicate instance
  */
 template <typename Iter, typename Predicate>
-void trim_right(Iter begin, Iter& end, Predicate&& p)
+constexpr void trim_right(Iter begin, Iter& end, Predicate p)
 {
     for ( ; begin != end; --end) {
         if (!p(*(end-1))) {
@@ -70,7 +70,7 @@ void trim_right(Iter begin, Iter& end, Predicate&& p)
  * @param p Predicate instance
  */
 template <typename Iter, typename Predicate>
-void trim(Iter& begin, Iter& end, Predicate p)
+constexpr void trim(Iter& begin, Iter& end, Predicate p)
 {
     trim_left(begin, end, p);
     trim_right(begin, end, p);
@@ -85,7 +85,7 @@ void trim(Iter& begin, Iter& end, Predicate p)
  * @param p Predicate instances
  */
 template <typename Predicate, typename CharT, typename Traits>
-void trim_left(std::basic_string_view<CharT, Traits>& str, Predicate&& p)
+constexpr void trim_left(std::basic_string_view<CharT, Traits>& str, Predicate&& p)
 {
     auto begin = str.begin();
     auto end = str.end();
@@ -103,7 +103,7 @@ void trim_left(std::basic_string_view<CharT, Traits>& str, Predicate&& p)
  * @param p Predicate instances
  */
 template <typename Predicate, typename CharT, typename Traits>
-void trim_right(std::basic_string_view<CharT, Traits>& str, Predicate&& p)
+constexpr void trim_right(std::basic_string_view<CharT, Traits>& str, Predicate&& p)
 {
     auto begin = str.begin();
     auto end = str.end();
@@ -121,7 +121,7 @@ void trim_right(std::basic_string_view<CharT, Traits>& str, Predicate&& p)
  * @param p Predicate instances
  */
 template <typename Predicate, typename CharT, typename Traits>
-void trim(std::basic_string_view<CharT, Traits>& str, Predicate&& p)
+constexpr void trim(std::basic_string_view<CharT, Traits>& str, Predicate&& p)
 {
     auto begin = str.begin();
     auto end = str.end();

diff --git a/include/malbolge/cpu_instruction.hpp b/include/malbolge/cpu_instruction.hpp
@@ -83,7 +83,8 @@ constexpr auto all = std::array{
  * @return True if valid
  */
 template <typename T>
-inline constexpr bool is_cpu_instruction(T instruction)
+[[nodiscard]]
+constexpr bool is_cpu_instruction(T instruction) noexcept
 {
     return std::any_of(cpu_instruction::all.begin(),
                        cpu_instruction::all.end(),
@@ -103,7 +104,8 @@ constexpr auto graphical_ascii_range = std::pair<char, char>{33, 126};
  * @return True if graphical ASCII
  */
 template <typename T>
-inline constexpr bool is_graphical_ascii(T c)
+[[nodiscard]]
+constexpr bool is_graphical_ascii(T c) noexcept
 {
     return c >= graphical_ascii_range.first &&
            c <= graphical_ascii_range.second;
@@ -124,15 +126,17 @@ constexpr auto size = (graphical_ascii_range.second -
  * @return Character in the pre-cipher at @a index, or an empty optional if
  * @a index is out of range
  */
-std::optional<char> pre(std::size_t index);
+[[nodiscard]]
+std::optional<char> pre(std::size_t index) noexcept;
 
 /** Returns the post-ciphered character at @a index.
  *
  * @param index Index into post-cipher array
  * @return Character in the post-cipher at @a index, or an empty optional if
  * @a index is out of range
  */
-std::optional<char> post(std::size_t index);
+[[nodiscard]]
+std::optional<char> post(std::size_t index) noexcept;
 }
 
 /** Performs a pre-instruction cipher on @a input.
@@ -144,7 +148,8 @@ std::optional<char> post(std::size_t index);
  * within in the graphical ASCII range
  */
 template <typename T>
-std::optional<char> pre_cipher_instruction(T input, std::size_t index)
+[[nodiscard]]
+std::optional<char> pre_cipher_instruction(T input, std::size_t index) noexcept
 {
     if (!is_graphical_ascii(input)) {
         return {};
@@ -162,7 +167,8 @@ std::optional<char> pre_cipher_instruction(T input, std::size_t index)
  * within in the graphical ASCII range
  */
 template <typename T>
-std::optional<char> post_cipher_instruction(T input)
+[[nodiscard]]
+std::optional<char> post_cipher_instruction(T input) noexcept
 {
     if (!is_graphical_ascii(input)) {
         return {};

diff --git a/include/malbolge/debugger/script_parser.hpp b/include/malbolge/debugger/script_parser.hpp
@@ -24,6 +24,7 @@ namespace script
  * @return Function sequence
  * @exception parse_exception Thrown if the parsing failed
  */
+[[nodiscard]]
 functions::sequence parse(std::istream& stream);
 
 /** Parse a debugger script loaded from @a path.
@@ -35,6 +36,7 @@ functions::sequence parse(std::istream& stream);
  * @exception parse_exception Thrown if the parsing failed
  * @exception system_exception Thrown if @a path could not be opened
  */
+[[nodiscard]]
 functions::sequence parse(const std::filesystem::path& path);
 }
 }

diff --git a/include/malbolge/debugger/script_runner.hpp b/include/malbolge/debugger/script_runner.hpp
@@ -63,7 +63,8 @@ class function_argument
      *
      * @return Argument name
      */
-    static constexpr std::string_view name()
+    [[nodiscard]]
+    static constexpr std::string_view name() noexcept
     {
         return name_type::value();
     }
@@ -72,7 +73,7 @@ class function_argument
      *
      * @param v Value to assign
      */
-    constexpr function_argument(value_type v = static_cast<value_type>(DefaultValue{})) :
+    constexpr function_argument(value_type v = static_cast<value_type>(DefaultValue{})) noexcept :
         value(std::move(v))
     {}
 
@@ -81,7 +82,8 @@ class function_argument
      * @param other Instance to compare against
      * @return Ordering
      */
-    auto operator<=>(const function_argument& other) const = default;
+    [[nodiscard]]
+    auto operator<=>(const function_argument& other) const noexcept = default;
 
     /** Function value.
      */
@@ -154,7 +156,7 @@ class function
      * @param cargs Constructor function arguments
      */
     template <typename... ConArgs>
-    constexpr function(ConArgs... cargs)
+    constexpr function(ConArgs... cargs) noexcept
     {
         static_assert(sizeof...(ConArgs) <= sizeof...(Args),
                       "Number of ConArgs must not be greater than Args");
@@ -178,7 +180,8 @@ class function
      * @return Argument instance reference
      */
     template <typename ArgName>
-    constexpr const auto& arg() const
+    [[nodiscard]]
+    constexpr const auto& arg() const noexcept
     {
         using index = boost::mp11::mp_find_if<
                 args_type,
@@ -198,7 +201,8 @@ class function
      * @return Argument instance value
      */
     template <typename ArgName>
-    constexpr const auto& value() const
+    [[nodiscard]]
+    constexpr const auto& value() const noexcept
     {
         return arg<ArgName>().value;
     }
@@ -207,7 +211,8 @@ class function
      *
      * @return Argument name
      */
-    static constexpr std::string_view name()
+    [[nodiscard]]
+    static constexpr std::string_view name() noexcept
     {
         return name_type::value();
     }
@@ -217,7 +222,8 @@ class function
      * @param other Instance to compare against
      * @return Ordering
      */
-    auto operator<=>(const function& other) const = default;
+    [[nodiscard]]
+    auto operator<=>(const function& other) const noexcept = default;
 
     /** Function arguments.
      */

diff --git a/include/malbolge/exception.hpp b/include/malbolge/exception.hpp
@@ -31,8 +31,8 @@ struct source_location
      * @param l Line number
      * @param c Column number
      */
-    source_location(math::ternary::underlying_type l = 1,
-                    math::ternary::underlying_type c = 1) :
+    constexpr source_location(math::ternary::underlying_type l = 1,
+                              math::ternary::underlying_type c = 1) noexcept:
         line{l},
         column{c}
     {}
@@ -42,7 +42,9 @@ struct source_location
      * @param other Instance to compare against
      * @return Ordering
      */
-    auto operator<=>(const source_location& other) const = default;
+    [[nodiscard]]
+    constexpr auto
+    operator<=>(const source_location& other) const noexcept = default;
 
     math::ternary::underlying_type line;    ///< Line number
     math::ternary::underlying_type column;  ///< Column number
@@ -58,6 +60,7 @@ using optional_source_location = std::optional<source_location>;
  * @param loc Source location
  * @return String equivalent to it
  */
+[[nodiscard]]
 std::string to_string(const optional_source_location& loc);
 
 /** Textual streaming operator for optional_source_location.
@@ -96,7 +99,8 @@ class parse_exception : public basic_exception
      * This is used for rethrowing with an updated source location
      * @return Constructor message
      */
-    const std::string& message() const
+    [[nodiscard]]
+    const std::string& message() const noexcept
     {
         return msg_;
     }
@@ -105,6 +109,7 @@ class parse_exception : public basic_exception
      *
      * @return Location set
      */
+    [[nodiscard]]
     bool has_location() const noexcept
     {
         return !!loc_;
@@ -114,6 +119,7 @@ class parse_exception : public basic_exception
      *
      * @return The location, may be empty
      */
+    [[nodiscard]]
     optional_source_location location() const noexcept
     {
         return loc_;
@@ -145,6 +151,7 @@ class execution_exception : public basic_exception
      *
      * @return Execution step
      */
+    [[nodiscard]]
     std::size_t step() const noexcept
     {
         return step_;
@@ -186,6 +193,7 @@ class system_exception : public basic_exception
      *
      * @return Error code
      */
+    [[nodiscard]]
     const std::error_code& code() const noexcept
     {
         return code_;

diff --git a/include/malbolge/loader.hpp b/include/malbolge/loader.hpp
@@ -46,6 +46,7 @@ std::ostream& operator<<(std::ostream& stream, load_normalised_mode mode);
  * @exception parse_exception Thrown if the program contains errors
  */
 template <typename InputIt>
+[[nodiscard]]
 virtual_memory load(InputIt first,
                     InputIt last,
                     load_normalised_mode mode = load_normalised_mode::AUTO)
@@ -135,6 +136,7 @@ template <typename R,
           std::enable_if_t<!std::is_same_v<std::decay_t<R>,
                                            std::filesystem::path>,
                            int> = 0>
+[[nodiscard]]
 virtual_memory load(R&& range,
                     load_normalised_mode mode = load_normalised_mode::AUTO)
 {
@@ -153,6 +155,7 @@ virtual_memory load(R&& range,
  * @exception parse_exception Thrown if the program cannot be read or contains
  * errors
  */
+[[nodiscard]]
 virtual_memory load(const std::filesystem::path& path,
                     load_normalised_mode mode = load_normalised_mode::AUTO);
 
@@ -163,5 +166,6 @@ virtual_memory load(const std::filesystem::path& path,
  * @return Virtual memory image with the program at the start
  * @exception parse_exception Thrown if the program contains errors
  */
+[[nodiscard]]
 virtual_memory load_from_cin(load_normalised_mode mode = load_normalised_mode::AUTO);
 }