Documentation! (#141)

* Fixing spelling errors in comment.

* Adding Doxygen and preset.

* Documentation now building locally.

* Moving machines - still warnings to resolve.

* Update doxyfile

* More documentation fixes.

* More test cleanup and fixing unit tests.

* Small improvements to functional

* Fixing doxygen warnings.

* Checkpoint in doxygen warning fixes.

* Cleaning out final doxygen warnings.

Author: sean-parent

.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)
 */
 /**************************************************************************************************/
 /*!