Documentation generation for function callbacks

RELEASE-NOTES.md

@@ -41,6 +41,7 @@ The Axom project release numbers follow [Semantic Versioning](http://semver.org/
 - Inlet: Added `get<std::vector<T>>` for retrieving arrays without index information
 - Inlet: Added a new `Writer` for generating JSON schemas which can be used by text editors
   for autocompletion
+- Inlet: SphinxWriter will now document the signature of function callbacks added to a schema
 
 ### Changed
 - The Sidre Datastore no longer rewires Conduit's error handlers to SLIC by default. 
@@ -59,7 +60,6 @@ The Axom project release numbers follow [Semantic Versioning](http://semver.org/
   more than just unit tests.
 - Inlet: Input file functions can now be of arbitrary signature subject to type and arity
   restrictions
-- Updated built-in TPL `fmt` to master branch snapshot, March 26, 2021.
 - Updated TPL `conduit` to version 0.6.0 released Nov 2, 2020.
 - Updated built-in TPL `sparsehash` to version 2.0.4 released Aug 11, 2020.
 - Inlet: Exposed primal::Vector in Lua for use in input-file-defined functions
@@ -74,7 +74,9 @@ The Axom project release numbers follow [Semantic Versioning](http://semver.org/
 - Required collections no longer fail Inlet verification if they are empty in the input file
 - Inlet: `operator bool` for `Field` and `Container` has been replaced with more precise `isUserProvided`
   and `exists`, which also returns `true` if a default value was specified.
-- Updated built-in TPL `fmt` to version 7.1.3 released Nov 24, 2020.
+- Updated built-in TPL `fmt` to master branch snapshot, March 26, 2021.
+- Inlet: SphinxWriter will now print only one element schema per container instead of
+  printing the same schema for each element in the container
 
 ### Fixed
 - Updated to new BLT version that does not fail when ClangFormat returns an empty

src/axom/inlet/Container.cpp

@@ -162,7 +162,7 @@ Container& Container::addStructCollection(const std::string& name,
     const auto result = m_reader.getIndices(fullName, indices);
     if(result == ReaderResult::Success)
     {
-      container.addIndicesGroup(indices, description);
+      container.addIndicesGroup(indices, description, true);
     }
     markRetrievalStatus(*container.m_sidreGroup, result);
     markAsStructCollection(*container.m_sidreGroup);
@@ -547,6 +547,36 @@ void addIndexViewToGroup(sidre::Group& group, const VariantKey& index)
   }
 }
 
+/*!
+ *****************************************************************************
+ * \brief Writes function signature information to the sidre Group associated
+ * with an inlet::Function
+ * 
+ * \param [in] ret_type The function's return type
+ * \param [in] arg_types The function's argument types
+ * \param [inout] group The group to add to
+ * 
+ * The structure of the function signature information is as follows:
+ * <group>
+ *  ├─• function_arguments <integer array>
+ *  └─• return_type <integer>
+ *****************************************************************************
+ */
+void addSignatureToGroup(const FunctionTag ret_type,
+                         const std::vector<FunctionTag>& arg_types,
+                         sidre::Group* group)
+{
+  group->createViewScalar("return_type", static_cast<int>(ret_type));
+  auto args_view = group->createViewAndAllocate("function_arguments",
+                                                sidre::INT_ID,
+                                                arg_types.size());
+  int* args_array = args_view->getArray();
+  for(const auto arg_type : arg_types)
+  {
+    *args_array++ = static_cast<int>(arg_type);
+  }
+}
+
 std::vector<VariantKey> collectionIndices(const Container& container,
                                           bool trimAbsolute)
 {
@@ -615,7 +645,8 @@ std::vector<std::pair<std::string, std::string>> collectionIndicesWithPaths(
 
 template <typename Key>
 void Container::addIndicesGroup(const std::vector<Key>& indices,
-                                const std::string& description)
+                                const std::string& description,
+                                const bool add_containers)
 {
   sidre::Group* indices_group =
     m_sidreGroup->createGroup(detail::COLLECTION_INDICES_NAME,
@@ -626,7 +657,10 @@ void Container::addIndicesGroup(const std::vector<Key>& indices,
   {
     const std::string string_idx =
       removeBeforeDelimiter(detail::indexToString(idx));
-    addContainer(string_idx, description);
+    if(add_containers)
+    {
+      addContainer(string_idx, description);
+    }
     std::string absolute = appendPrefix(m_name, detail::indexToString(idx));
     absolute = removeAllInstances(absolute, detail::COLLECTION_GROUP_NAME + "/");
     detail::addIndexViewToGroup(*indices_group, absolute);
@@ -682,7 +716,7 @@ Verifiable<Container>& Container::addPrimitiveArray(const std::string& name,
     // Copy the indices to the datastore to keep track of integer vs. string indices
     if(!indices.empty())
     {
-      container.addIndicesGroup(indices, description);
+      container.addIndicesGroup(indices, description, false);
     }
     return container;
   }
@@ -724,6 +758,7 @@ Verifiable<Function>& Container::addFunction(const std::string& name,
     SLIC_ERROR_IF(
       sidreGroup == nullptr,
       fmt::format("Failed to create Sidre group with name '{0}'", fullName));
+    detail::addSignatureToGroup(ret_type, arg_types, sidreGroup);
     // If a pathOverride is specified, needed when Inlet-internal groups
     // are part of fullName
     std::string lookupPath = (pathOverride.empty()) ? fullName : pathOverride;
@@ -1076,5 +1111,11 @@ Container::getChildFields() const
   return m_fieldChildren;
 }
 
-}  // end namespace inlet
-}  // end namespace axom
+const std::unordered_map<std::string, std::unique_ptr<Function>>&
+Container::getChildFunctions() const
+{
+  return m_functionChildren;
+}
+
+}  // namespace inlet
+}  // namespace axom

src/axom/inlet/Container.hpp

@@ -894,6 +894,15 @@ class Container : public Verifiable<Container>
   const std::unordered_map<std::string, std::unique_ptr<Container>>&
   getChildContainers() const;
 
+  /*!
+   *****************************************************************************
+   * \return An unordered map from Function names to the child Function pointers for 
+   * this Container.
+   *****************************************************************************
+   */
+  const std::unordered_map<std::string, std::unique_ptr<Function>>&
+  getChildFunctions() const;
+
   /*!
    *****************************************************************************
    * \return The full name of this Container.
@@ -1191,16 +1200,18 @@ class Container : public Verifiable<Container>
   /*!
    *******************************************************************************
    * \brief Adds a group containing the indices of a collection to the calling 
-   * container and a subcontainer for each index
+   * container and optionally a subcontainer for each index
    * 
    * \param [in] indices The indices to add
    * \param [in] description The optional description of the subcontainers
+   * \param [in] add_containers Whether to add a subcontainer for each index
    * \tparam Key The type of the indices to add
    *******************************************************************************
    */
   template <typename Key>
   void addIndicesGroup(const std::vector<Key>& indices,
-                       const std::string& description = "");
+                       const std::string& description = "",
+                       const bool add_containers = false);
 
   /*!
    *****************************************************************************

src/axom/inlet/Function.hpp

@@ -551,6 +551,16 @@ class Function : public Verifiable<Function>
     return m_func.call<Ret>(std::forward<Args>(args)...);
   }
 
+  /*!
+   *****************************************************************************
+   * \brief Returns pointer to the Sidre Group class for this Function.
+   *
+   * Provides access to the Sidre Group class that holds all the stored
+   * information for this Function instance.
+   *****************************************************************************
+   */
+  const axom::sidre::Group* sidreGroup() const { return m_sidreGroup; };
+
   /*!
    *******************************************************************************
    * \brief Checks whether the function exists

src/axom/inlet/Inlet.cpp

@@ -73,8 +73,9 @@ void writerHelper(Writer& writer, const Container& container)
 {
   // Use a pre-order traversal for readability
   writer.documentContainer(container);
-  // Only visit a single element of a collection
-  if(isCollectionGroup(container.name()))
+  // Only visit a single element of a *struct* collection
+  if(isCollectionGroup(container.name()) &&
+     container.sidreGroup()->hasView(detail::STRUCT_COLLECTION_FLAG))
   {
     auto indices = detail::collectionIndices(container);
     // Just use the first index