Add documentation for the interfaces

doc/CMakeLists.txt

@@ -26,6 +26,7 @@ add_doxygen_doc(
     EXTRACT_ALL YES
     ENUM_VALUES_PER_LINE 1
     FULL_PATH_NAMES YES
+    PREDEFINED DOXYGEN
 )
 
 include(SphinxDoc)

src/include/migraph/context.hpp

@@ -9,6 +9,17 @@
 
 namespace migraph {
 
+#ifdef DOXYGEN
+
+/// A context is used to store internal data for a `target`. A context is
+/// constructed by a target during compilation and passed to the operations
+/// during `eval`.
+struct context
+{
+};
+
+#else
+
 /*
 * Type-erased interface for:
 *
@@ -177,6 +188,8 @@ inline const ValueType& any_cast(const context& x)
     return *y;
 }
 
+#endif
+
 } // namespace migraph
 
 #endif

src/include/migraph/operation.hpp

@@ -13,6 +13,37 @@
 
 namespace migraph {
 
+#ifdef DOXYGEN
+
+/// The operation interface represents an action an instruction will do. All
+/// operation classes must be CopyConstructible.
+struct operation
+{
+    /// A unique name identifying the operation
+    std::string name() const;
+    /// This is used to compute the resulting shape from an operation. If an
+    /// operation cannot be run with input shapes, then it should throw an
+    /// exception.
+    shape compute_shape(std::vector<shape> input) const;
+    /**
+     * @brief This performs the operation's computation
+     *
+     * @param ctx This is the context created by the `target` during compilation. Implementations
+     * can use the target's `context` class rather than the `context` interface class.
+     * @param output This is the output shape. It is equivalent to running `compute_shape` with each
+     * `shape` of the `argument`.
+     * @param input This is the `argument` result from the previous instuction's computation.
+     * @return Return an `argument` of the result computation. The `shape` of `argument` should be
+     * the same the `output` shape.
+     */
+    argument compute(context& ctx, shape output, std::vector<argument> input) const;
+    /// An optional stream operator to print the operation. When this is not
+    /// implemented, it will just print the operation's name.
+    friend std::ostream& operator<<(std::ostream& os, const operation& op);
+};
+
+#else
+
 namespace operation_stream {
 
 template <class T>
@@ -250,6 +281,8 @@ inline const ValueType& any_cast(const operation& x)
     return *y;
 }
 
+#endif
+
 } // namespace migraph
 
 #endif

src/include/migraph/pass.hpp

@@ -11,6 +11,19 @@ namespace migraph {
 
 struct program;
 
+#ifdef DOXYGEN
+
+/// This applies a transformation to the instruction in a `program`
+struct pass
+{
+    /// A unique name used to identify the pass
+    std::string name() const;
+    /// Run the pass on the program
+    void apply(program& p) const;
+};
+
+#else
+
 /*
  * Type-erased interface for:
  *
@@ -199,6 +212,8 @@ inline const ValueType& any_cast(const pass& x)
     return *y;
 }
 
+#endif
+
 } // namespace migraph
 
 #endif

src/include/migraph/target.hpp

@@ -12,7 +12,30 @@
 
 namespace migraph {
 
-struct program;
+#if DOXYGEN
+
+/// A compilation target
+struct target
+{
+    /// A unique name used to identify the target
+    std::string name() const;
+    /// The transformation passes to be run
+    /**
+     * @brief The transformation pass to be run during compilation.
+     * @details [long description]
+     *
+     * @param ctx This is the target-dependent context that is created by `get_context`
+     * @return The passes to be ran
+     */
+    std::vector<pass> get_passes(context& ctx) const;
+    /**
+     * @brief Construct a context for the target.
+     * @return The context to be used during compilation and execution.
+     */
+    context get_context() const;
+};
+
+#else
 
 /*
  * Type-erased interface for:
@@ -216,6 +239,8 @@ inline const ValueType& any_cast(const target& x)
     return *y;
 }
 
+#endif
+
 } // namespace migraph
 
 #endif

tools/include/context.hpp

@@ -9,10 +9,22 @@
 
 namespace migraph {
 
+#ifdef DOXYGEN
+
+/// A context is used to store internal data for a `target`. A context is
+/// constructed by a target during compilation and passed to the operations
+/// during `eval`.
+struct context
+{};
+
+#else
+
 <%
 interface('context')
 %>
 
+#endif
+
 } // namespace migraph
 
 #endif

tools/include/operation.hpp

@@ -13,6 +13,34 @@
 
 namespace migraph {
 
+#ifdef DOXYGEN
+
+/// The operation interface represents an action an instruction will perform. All
+/// operation classes must be CopyConstructible.
+struct operation
+{
+    /// A unique name identifying the operation
+    std::string name() const;
+    /// This is used to compute the resulting shape from an operation. If an
+    /// operation cannot be run with input shapes, then it should throw an
+    /// exception.
+    shape compute_shape(std::vector<shape> input) const;
+    /**
+     * @brief This performs the operation's computation
+     * 
+     * @param ctx This is the context created by the `target` during compilation. Implementations can use the target's `context` class rather than the `context` interface class.
+     * @param output This is the output shape. It is equivalent to running `compute_shape` with each `shape` of the `argument`.
+     * @param input This is the `argument` result from the previous instuction's computation.
+     * @return Return an `argument` of the result computation. The `shape` of `argument` should be the same the `output` shape.
+     */
+    argument compute(context& ctx, shape output, std::vector<argument> input) const;
+    /// An optional stream operator to print the operation. When this is not
+    /// implemented, it will just print the operation's name.
+    friend std::ostream & operator<<(std::ostream & os, const operation & op);
+};
+
+#else
+
 namespace operation_stream {
 
 template <class T>
@@ -38,6 +66,8 @@ interface('operation',
 )
 %>
 
+#endif
+
 } // namespace migraph
 
 #endif

tools/include/pass.hpp

@@ -11,6 +11,19 @@ namespace migraph {
 
 struct program;
 
+#ifdef DOXYGEN
+
+/// This applies a transformation to the instruction in a `program`
+struct pass
+{
+    /// A unique name used to identify the pass
+    std::string name() const;
+    /// Run the pass on the program
+    void apply(program & p) const;
+};
+
+#else
+
 <%
 interface('pass',
     virtual('name', returns='std::string', const=True),
@@ -18,6 +31,8 @@ interface('pass',
 )
 %>
 
+#endif
+
 } // namespace migraph
 
 #endif

tools/include/target.hpp

@@ -12,7 +12,30 @@
 
 namespace migraph {
 
-struct program;
+#if DOXYGEN
+
+/// A compilation target
+struct target
+{
+    /// A unique name used to identify the target
+    std::string name() const;
+    /// The transformation passes to be run
+    /**
+     * @brief The transformation pass to be run during compilation.
+     * @details [long description]
+     * 
+     * @param ctx This is the target-dependent context that is created by `get_context`
+     * @return The passes to be ran
+     */
+    std::vector<pass> get_passes(context& ctx) const;
+    /**
+     * @brief Construct a context for the target.
+     * @return The context to be used during compilation and execution.
+     */
+    context get_context() const;
+};
+
+#else
 
 <%
 interface('target',
@@ -22,6 +45,8 @@ interface('target',
 )
 %>
 
+#endif
+
 } // namespace migraph
 
 #endif

tools/te.py

@@ -239,7 +239,8 @@ def convert_member(d, struct_name):
             'member_const': '',
             'friend': '',
             'this': '(*this)',
-            'using': ''
+            'using': '',
+            'brief': ''
         }
         args = []
         params = []
@@ -266,6 +267,8 @@ def convert_member(d, struct_name):
                 member['default'] = t
             elif x == 'using':
                 member['using'] = 'using {};'.format(d[name]['using'])
+            elif x == '__brief__':
+                member['doc'] = '/// ' + t
             elif x.startswith('__') and x.endswith('__'):
                 continue
             else: