Documentation!

.github/workflows/doxygen.yml

@@ -0,0 +1,26 @@
+name: Doxygen
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v2
+
+      - name: Install Doxygen
+        run: sudo apt-get update && sudo apt-get install -y doxygen
+
+      - name: Build documentation
+        run: doxygen documentation/doxyfile
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: build/asl-docs/html 

.gitignore

@@ -9,3 +9,4 @@ documentation/doxyfile.bak
 build_asl/
 .vs/
 .vscode/settings.json
+/.cache

CMakeLists.txt

@@ -17,6 +17,16 @@ endif(NOT DEFINED CMAKE_CXX_STANDARD)
 
 set(CMAKE_XCODE_ATTRIBUTE_CLANG_CXX_LIBRARY "libc++")
 
+# Create symlink to compile_commands.json for clangd
+if(CMAKE_EXPORT_COMPILE_COMMANDS)
+    add_custom_target(clangd_compile_commands ALL
+        COMMAND ${CMAKE_COMMAND} -E create_symlink
+            ${CMAKE_BINARY_DIR}/compile_commands.json
+            ${CMAKE_SOURCE_DIR}/compile_commands.json
+        COMMENT "Creating symlink to compile_commands.json for clangd"
+    )
+endif()
+
 project(adobe-source-libraries CXX)
 
 # https://github.com/boostorg/boost/releases
@@ -49,3 +59,18 @@ add_subdirectory(source)
 if(BUILD_TESTING)
     add_subdirectory(test)
 endif()
+
+find_package(Doxygen)
+
+if(DOXYGEN_FOUND)
+    set(DOXYGEN_IN ${CMAKE_CURRENT_SOURCE_DIR}/documentation/doxyfile)
+
+    add_custom_target(doxygen ALL
+        COMMAND ${DOXYGEN_EXECUTABLE} ${DOXYGEN_IN}
+        WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
+        COMMENT "Generating API documentation with Doxygen"
+        VERBATIM
+    )
+else()
+    message(WARNING "Doxygen not found - documentation will not be built")
+endif()

CMakePresets.json

@@ -138,6 +138,16 @@
                     "enableClangTidyCodeAnalysis": true
                 }
             }
+        },
+        {
+            "name": "docs",
+            "displayName": "docs",
+            "description": "Build Doxygen documentation",
+            "generator": "Ninja",
+            "binaryDir": "${sourceParentDir}/build/asl-docs",
+            "cacheVariables": {
+                "CMAKE_BUILD_TYPE": "DEBUG"
+            }
         }
     ],
     "buildPresets": [
@@ -146,6 +156,13 @@
             "description": "",
             "displayName": "",
             "configurePreset": "debug"
+        },
+        {
+            "name": "docs",
+            "description": "",
+            "displayName": "",
+            "configurePreset": "docs",
+            "targets": [ "doxygen" ]
         }
     ],
     "testPresets": [

adobe/adam.hpp

@@ -25,11 +25,11 @@
 
 /*
 
-    REVISIT (sparent) : It would be best to detangle the sheet from
-    the virtual machine. The way to do this is to allow for funciton
+    REVISIT (sparent) : It would be best to untangle the sheet from
+    the virtual machine. The way to do this is to allow for function
     objects to be passed instead of line positions and expression
     arrays. The function object could bind to the line_position_t and
-    the array.... This would allow for easier programatic driving.
+    the array.... This would allow for easier programmatic driving.
 
 */
 
@@ -190,8 +190,6 @@ class sheet_t : boost::noncopyable {
       \param name name of the cell being added.
 
       \param value value for the cell.
-
-      \param initializer expression to be evaluated for the cell's value.
     */
     void add_constant(name_t name, any_regular_t value);
 
@@ -233,7 +231,7 @@ class sheet_t : boost::noncopyable {
       \param linked specifies whether or not the output value is
       automatically applied back to the input value of the cell.
 
-      \param position position in the parse of the initializer definition.
+      \param position1 position in the parse of the initializer definition.
 
       \param initializer expression to be evaluated for the cell's value
 
@@ -254,7 +252,7 @@ class sheet_t : boost::noncopyable {
 
         \param name name of the cell being added.
 
-        \param inital initial value of the cell.
+        \param initial initial value of the cell.
     */
     void add_interface(name_t name, any_regular_t initial);
 
@@ -288,7 +286,7 @@ class sheet_t : boost::noncopyable {
       Establishes a callback for a cell to be called when the value of the
       cell changes.
 
-      \param cell the name of the cell to monitor.
+      \param name the name of the cell to monitor.
 
       \param proc the \ref concept_convertible_to_function to be called
       with the new cell value.

adobe/algorithm.hpp

@@ -94,7 +94,7 @@ using.
     - \ref minmax
     - \ref rotate
 
-\sa \ref stldoc_index
+
 
 \defgroup mutating_algorithm Mutating Algorithms
 \ingroup algorithm

adobe/algorithm/binary_search.hpp

@@ -51,8 +51,8 @@ to [1] \c x if such a value s present and \c l if no such elment exists. \c bina
 takes an optional comparision function and uses \c adobe::less() if not provided.
 
 \requirements
-    - \c I is a model of \ref stldoc_ForwardIterator.
-    - \c C is a model of \ref stldoc_LessThanComparable.
+    - \c I is a model of [ForwardIterator](https://www.boost.org/sgi/stl/ForwardIterator.html).
+    - \c C is a model of [LessThanComparable](https://www.boost.org/sgi/stl/LessThanComparable.html).
     - <code>value_type(I) == argument_type(C)</code>
 
 \pre
@@ -63,31 +63,31 @@ of iterators \c i and \c j in <code>[f, l)</code> such that \c i precedes \c j,
 
 \complexity
 The number of comparisons is logarithmic: at most <code>log(l - f) + 2</code>. If I is a
-\ref stldoc_RandomAccessIterator then the number of steps through the range is also logarithmic;
+[RandomAccessIterator](https://www.boost.org/sgi/stl/RandomAccessIterator.html) then the number of steps through the range is also logarithmic;
 otherwise, the number of steps is proportional to last - first. [2]
 
 \notes
 [1] Note that you may use an ordering that is a strict weak ordering but not a total ordering; that
 is, there might be values x and y such that x < y, x > y, and x == y are all false.
-(See the \ref stldoc_LessThanComparable requirements for a more complete discussion.) Finding \c x
+(See the [LessThanComparable](https://www.boost.org/sgi/stl/LessThanComparable.html) requirements for a more complete discussion.) Finding \c x
 in the range <code>[f, l)</code>, then, doesn't mean finding an element that is equal to \c x but
 rather one that is equivalent to \c x: one that is neither greater than nor less than \c x. If
 you're using a total ordering, however (if you're using \c strcmp, for example, or if you're using
 ordinary arithmetic comparison on integers), then you can ignore this technical distinction: for a
 total ordering, equality and equivalence are the same.
 
-[2] This difference between \ref stldoc_RandomAccessIterator and \ref stldoc_ForwardIterator is
-simply because advance is constant time for \ref stldoc_RandomAccessIterator and linear time for
-\ref stldoc_ForwardIterator.
+[2] This difference between [RandomAccessIterator](https://www.boost.org/sgi/stl/RandomAccessIterator.html) and [ForwardIterator](https://www.boost.org/sgi/stl/ForwardIterator.html) is
+simply because advance is constant time for [RandomAccessIterator](https://www.boost.org/sgi/stl/RandomAccessIterator.html) and linear time for
+[ForwardIterator](https://www.boost.org/sgi/stl/ForwardIterator.html).
 
 \note
-\c binary_search() differs from \ref stldoc_binary_search in that it returns an iterator to the
+\c binary_search() differs from [std::binary_search](https://www.boost.org/sgi/stl/binary_search.html) in that it returns an iterator to the
 first element rather than simply a \c bool. This is commonly a more useful function.
 \c binary_search is similar to \ref lower_bound except it returns \c l if no element matching \c x
 exists.
 
 \see
-    - STL documentation for \ref stldoc_binary_search
+    - [STL documentation for binary_search](https://www.boost.org/sgi/stl/binary_search.html)
     - \ref lower_bound
     - \ref upper_bound
     - \ref equal_range

adobe/algorithm/copy.hpp

@@ -27,9 +27,9 @@ namespace adobe {
 \ingroup mutating_algorithm
 
 \see
-    - STL documentation for \ref stldoc_copy
-    - STL documentation for \ref stldoc_copy_n
-    - STL documentation for \ref stldoc_copy_backward
+    - [STL documentation for copy](https://www.boost.org/sgi/stl/copy.html)
+    - [STL documentation for copy_n](https://www.boost.org/sgi/stl/copy_n.html)
+    - [STL documentation for copy_backward](https://www.boost.org/sgi/stl/copy_backward.html)
 */
 /**************************************************************************************************/
 

adobe/algorithm/count.hpp

@@ -27,8 +27,8 @@ namespace adobe {
 \ingroup non_mutating_algorithm
 
 \see
-    - STL documentation for \ref stldoc_count
-    - STL documentation for \ref stldoc_count_if
+    - [STL documentation for count](https://www.boost.org/sgi/stl/count.html)
+    - [STL documentation for count_if](https://www.boost.org/sgi/stl/count_if.html)
 */
 /**************************************************************************************************/
 /*!

adobe/algorithm/equal.hpp

@@ -26,7 +26,7 @@ namespace adobe {
 \ingroup non_mutating_algorithm
 
 \see
-    - STL documentation for \ref stldoc_equal
+    - [STL documentation for equal](https://www.boost.org/sgi/stl/equal.html)
 */
 /**************************************************************************************************/
 /*!

adobe/algorithm/equal_range.hpp

@@ -31,7 +31,7 @@
 \ingroup sorting
 
 \see
-    - STL documentation for \ref stldoc_equal_range
+    - [STL documentation for equal_range](https://www.boost.org/sgi/stl/equal_range.html)
 */
 
 /**************************************************************************************************/

adobe/algorithm/fill.hpp

@@ -25,7 +25,7 @@ namespace adobe {
 \ingroup mutating_algorithm
 
 \see
-    - STL documentation for \ref stldoc_fill
+    - [STL documentation for fill](https://www.boost.org/sgi/stl/fill.html)
 */
 /**************************************************************************************************/
 /*!

adobe/algorithm/filter.hpp

@@ -25,8 +25,7 @@ namespace adobe {
 \defgroup filter filter
 \ingroup mutating_algorithm
 
-Filter is similar to \c std::tranform. The \c op function is passed an instance of an \ref
-stldoc_output_iterator and can generate more than (or fewer than) a single result.
+Filter is similar to \c std::tranform. The \c op function is passed an instance of an [output_iterator](https://www.boost.org/sgi/stl/output_iterator.html) and can generate more than (or fewer than) a single result.
 
 The \c op function is called once for each item in the range <code>[first, last)</code>. The \c
 result parameter is passed into the first call to \c op, the result of \c op is passed to subsequent
@@ -35,8 +34,8 @@ calls to \c op.
 \see std::transform, std::remove
 
 \requirements
-    - \em I models \ref stldoc_input_iterator.
-    - \em O models \ref stldoc_output_iterator.
+    - \em I models [input_iterator](https://www.boost.org/sgi/stl/input_iterator.html).
+    - \em O models [output_iterator](https://www.boost.org/sgi/stl/output_iterator.html).
     - \em F models \ref concept_convertible_to_function with signature O op(value_type(I), O)
     - \em <code>[first, last)</code> is a valid range.
 

adobe/algorithm/find.hpp

@@ -28,11 +28,11 @@ namespace adobe {
 \ingroup non_mutating_algorithm
 
 \see
-    - STL documentation for \ref stldoc_find
-    - STL documentation for \ref stldoc_find_if
-    - STL documentation for \ref stldoc_find_end
-    - STL documentation for \ref stldoc_find_first_of
-    - STL documentation for \ref stldoc_adjacent_find
+    - [STL documentation for find](https://www.boost.org/sgi/stl/find.html)
+    - [STL documentation for find_if](https://www.boost.org/sgi/stl/find_if.html)
+    - [STL documentation for find_end](https://www.boost.org/sgi/stl/find_end.html)
+    - [STL documentation for find_first_of](https://www.boost.org/sgi/stl/find_first_of.html)
+    - [STL documentation for adjacent_find](https://www.boost.org/sgi/stl/adjacent_find.html)
 */
 
 /**************************************************************************************************/

adobe/algorithm/generate.hpp

@@ -23,7 +23,7 @@ namespace adobe {
 \ingroup mutating_algorithm
 
 \see
-    - STL documentation for \ref stldoc_generate
+    - [STL documentation for generate](https://www.boost.org/sgi/stl/generate.html)
 */
 /**************************************************************************************************/
 /*!

adobe/algorithm/heap.hpp

@@ -26,10 +26,10 @@ namespace adobe {
 \ingroup sorting
 
 \see
-    - STL documentation for \ref stldoc_push_heap
-    - STL documentation for \ref stldoc_pop_heap
-    - STL documentation for \ref stldoc_make_heap
-    - STL documentation for \ref stldoc_sort_heap
+    - [STL documentation for push_heap](https://www.boost.org/sgi/stl/push_heap.html)
+    - [STL documentation for pop_heap](https://www.boost.org/sgi/stl/pop_heap.html)
+    - [STL documentation for make_heap](https://www.boost.org/sgi/stl/make_heap.html)
+    - [STL documentation for sort_heap](https://www.boost.org/sgi/stl/sort_heap.html)
 */
 /**************************************************************************************************/
 /*!

adobe/algorithm/lexicographical_compare.hpp

@@ -26,7 +26,7 @@ namespace adobe {
 \ingroup sorting
 
 \see
-    - STL documentation for \ref stldoc_lexicographical_compare
+    - [STL documentation for lexicographical_compare](https://www.boost.org/sgi/stl/lexicographical_compare.html)
 */
 /**************************************************************************************************/
 /*!

adobe/algorithm/lower_bound.hpp

@@ -61,7 +61,7 @@ I lower_bound_n_(I f, N n, const T& x, C c, P p) {
 \ingroup sorting
 
 \see
-    - STL documentation for \ref stldoc_lower_bound
+    - [STL documentation for lower_bound](https://www.boost.org/sgi/stl/lower_bound.html)
 */
 
 /**************************************************************************************************/

adobe/algorithm/merge.hpp

@@ -26,7 +26,7 @@ namespace adobe {
 \ingroup sorting
 
 \see
-    - STL documentation for \ref stldoc_merge
+    - [STL documentation for merge](https://www.boost.org/sgi/stl/merge.html)
 */
 /**************************************************************************************************/
 /*!

adobe/algorithm/minmax.hpp

@@ -52,10 +52,10 @@ assert(a == 10);
 </code>
 
 \see
-    - STL documentation for \ref stldoc_min
-    - STL documentation for \ref stldoc_max
-    - STL documentation for \ref stldoc_min_element
-    - STL documentation for \ref stldoc_max_element
+    - [STL documentation for min](https://www.boost.org/sgi/stl/min.html)
+    - [STL documentation for max](https://www.boost.org/sgi/stl/max.html)
+    - [STL documentation for min_element](https://www.boost.org/sgi/stl/min_element.html)
+    - [STL documentation for max_element](https://www.boost.org/sgi/stl/max_element.html)
 */
 /**************************************************************************************************/
 

adobe/algorithm/mismatch.hpp

@@ -34,7 +34,7 @@ namespace adobe {
 \ingroup non_mutating_algorithm
 
 \see
-    - STL documentation for \ref stldoc_mismatch
+    - [STL documentation for mismatch](https://www.boost.org/sgi/stl/mismatch.html)
 */
 /**************************************************************************************************/
 /*!

adobe/algorithm/partition.hpp

@@ -26,8 +26,8 @@ namespace adobe {
 \ingroup mutating_algorithm
 
 \see
-    - STL documentation for \ref stldoc_partition
-    - STL documentation for \ref stldoc_stable_partition
+    - [STL documentation for partition](https://www.boost.org/sgi/stl/partition.html)
+    - [STL documentation for stable_partition](https://www.boost.org/sgi/stl/stable_partition.html)
 */
 /**************************************************************************************************/
 /*!

adobe/algorithm/permutation.hpp

@@ -26,8 +26,8 @@ namespace adobe {
 \ingroup sorting
 
 \see
-    - STL documentation for \ref stldoc_next_permutation
-    - STL documentation for \ref stldoc_prev_permutation
+    - [STL documentation for next_permutation](https://www.boost.org/sgi/stl/next_permutation.html)
+    - [STL documentation for prev_permutation](https://www.boost.org/sgi/stl/prev_permutation.html)
 */
 /**************************************************************************************************/
 /*!