Merge pull request oneapi-src#1006 from PatKamin/printing-capi-html-docs

[docs] Printing C API html docs
GeorgeWeb · Feb 2, 2024 · 8c604b0 · 8c604b0
2 parents caee5fe + c7b12bd
commit 8c604b0
Show file tree

Hide file tree

Showing 8 changed files with 518 additions and 873 deletions.
diff --git a/include/ur_print.h b/include/ur_print.h
diff --git a/scripts/generate_docs.py b/scripts/generate_docs.py
@@ -1,5 +1,5 @@
 """
- Copyright (C) 2022 Intel Corporation
+ Copyright (C) 2022-2024 Intel Corporation
 
  Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM Exceptions.
  See LICENSE.TXT
@@ -209,6 +209,7 @@ def generate_rst(docpath, section, namespace, tags, ver, rev, specs, meta):
         fout = os.path.join(dstpath, "api.rst")
         groupname = os.path.basename(dstpath).capitalize()
         util.makoWrite(fin, fout,
+            namespace=namespace,
             groupname=groupname,
             ver=ver,
             rev=rev,

diff --git a/scripts/templates/api_listing.mako b/scripts/templates/api_listing.mako
@@ -1,7 +1,7 @@
 <%!
 import re
 from templates import helper as th
-%><%
+from templates import print_helper as tph
 %>
 
 ==============================
@@ -264,3 +264,66 @@ ${th.make_type_name(n, tags, obj)}
 %endfor # obj in objects
 
 %endfor # s in specs
+
+#################################################################
+## Print API not part of the spec, needs to be generated separately
+#################################################################
+<%
+    x = tags['$x']
+    api_types_funcs = tph.get_api_types_funcs(specs, meta, namespace, tags)
+%>\
+## Generate Print API links table
+Print
+============================================================
+The Print API functions are helpful for printing Unified Runtime API objects'
+values as human-readable strings using C interface. Those functions are complimentary
+to the set of operators in the Print API C++ header (ur_print.hpp).
+
+Each function is named in the same style based on the Unified Runtime object name
+to be printed. See examples:
+
+To print the :any:`${x}_function_t` object's value, call:
+    :ref:`${x}PrintFunction`
+
+To print the :any:`${x}_kernel_arg_local_properties_t` object's value, call:
+    :ref:`${x}PrintKernelArgLocalProperties`
+
+There is also one 'extras' function in this API, which can be used for printing
+all values of given function's parameters - :any:`${x}PrintFunctionParams`.
+
+See :ref:`core/api:Print Functions` for the description of common parameters of Print API functions.
+
+* Functions
+%for func in api_types_funcs:
+    * :ref:`${func.c_name.replace("_", "-")}`
+%endfor
+
+## 'Extras' functions
+    * :ref:`${x}PrintFunctionParams`
+
+<%def name="generate_api_doc(func_name)">\
+.. _${func_name.replace("_", "-")}:
+
+${func_name}
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. doxygenfunction:: ${func_name}
+    :project: UnifiedRuntime
+</%def>
+
+## Generate Print API documentation
+Print Functions
+------------------------------------------------------------------------------
+All functions output strings to print to the :any:`buffer` of a given
+size :any:`buff_size`. The outputted string's size is retrieved
+with the :any:`out_size` parameter.
+It is required for :any:`buff_size` to be less than :any:`out_size` in order
+to write the output string to the :any:`buffer`. Otherwise, :any:`buffer`
+will not be modified.
+
+%for func in api_types_funcs:
+${generate_api_doc(func.c_name)}
+%endfor
+
+## 'Extras' functions
+${generate_api_doc(f'{x}PrintFunctionParams')}
diff --git a/scripts/templates/print.cpp.mako b/scripts/templates/print.cpp.mako
@@ -1,6 +1,6 @@
 <%!
 import re
-from templates import helper as th
+from templates import print_helper as tph
 %><%
     n=namespace
     N=n.upper()
@@ -9,7 +9,7 @@ from templates import helper as th
     X=x.upper()
 %>/*
  *
- * Copyright (C) 2023 Intel Corporation
+ * Copyright (C) 2023-2024 Intel Corporation
  *
  * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM Exceptions.
  * See LICENSE.TXT
@@ -52,41 +52,17 @@ ${x}_result_t str_copy(std::stringstream *ss, char *buff, const size_t buff_size
     return ${X}_RESULT_SUCCESS;
 }
 
-%for spec in specs:
-%for obj in spec['objects']:
-## ENUM #######################################################################
-%if re.match(r"enum", obj['type']):
-    ${x}_result_t ${th.make_func_name_with_prefix(f'{x}Print', obj['name'])}(enum ${th.make_enum_name(n, tags, obj)} value, char *buffer, const size_t buff_size, size_t *out_size) {
-        ${ss_copy("value")}
-    }
-
-## STRUCT #####################################################################
-%elif re.match(r"struct", obj['type']):
-    ${x}_result_t ${th.make_func_name_with_prefix(f'{x}Print', obj['name'])}(const ${obj['type']} ${th.make_type_name(n, tags, obj)} params, char *buffer, const size_t buff_size, size_t *out_size) {
-        ${ss_copy("params")}
-    }
-
-%endif
-%endfor # obj in spec['objects']
-%endfor
-
-%for tbl in th.get_pfncbtables(specs, meta, n, tags):
-%for obj in tbl['functions']:
 <%
-    name = th.make_pfncb_param_type(n, tags, obj)
-%>\
-${x}_result_t ${th.make_func_name_with_prefix(f'{x}Print', name)}(const struct ${th.make_pfncb_param_type(n, tags, obj)} *params, char *buffer, const size_t buff_size, size_t *out_size) {
-    ${ss_copy("params")}
+    api_types_funcs = tph.get_api_types_funcs(specs, meta, n, tags)
+%>
+%for func in api_types_funcs:
+${x}_result_t ${func.c_name}(${func.c_args}) {
+    ${ss_copy(func.print_arg.name)}
 }
 
-%endfor
 %endfor
 
 ${x}_result_t ${x}PrintFunctionParams(enum ${x}_function_t function, const void *params, char *buffer, const size_t buff_size, size_t *out_size) {
-    if (!params) {
-        return ${X}_RESULT_ERROR_INVALID_NULL_POINTER;
-    }
-
     std::stringstream ss;
     ${x}_result_t result = ${x}::extras::printFunctionParams(ss, function, params);
     if (result != ${X}_RESULT_SUCCESS) {

diff --git a/scripts/templates/print.h.mako b/scripts/templates/print.h.mako
@@ -1,6 +1,6 @@
 <%!
 import re
-from templates import helper as th
+from templates import print_helper as tph
 %><%
     n=namespace
     N=n.upper()
@@ -9,7 +9,7 @@ from templates import helper as th
     X=x.upper()
 %>/*
  *
- * Copyright (C) 2023 Intel Corporation
+ * Copyright (C) 2023-2024 Intel Corporation
  *
  * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM Exceptions.
  * See LICENSE.TXT
@@ -27,50 +27,19 @@ from templates import helper as th
 extern "C" {
 #endif
 
-## Declarations ###############################################################
-%for spec in specs:
-%for obj in spec['objects']:
-%if re.match(r"enum", obj['type']):
-    ///////////////////////////////////////////////////////////////////////////////
-    /// @brief Print ${th.make_enum_name(n, tags, obj)} enum
-    /// @returns
-    ///     - ::${X}_RESULT_SUCCESS
-    ///     - ::${X}_RESULT_ERROR_INVALID_NULL_POINTER
-    ///         - `NULL == buffer`
-    ///     - ::${X}_RESULT_ERROR_INVALID_SIZE
-    ///         - `buff_size < out_size`
-    ${X}_APIEXPORT ${x}_result_t ${X}_APICALL ${th.make_func_name_with_prefix(f'{x}Print', obj['name'])}(enum ${th.make_enum_name(n, tags, obj)} value, char *buffer, const size_t buff_size, size_t *out_size);
-
-%elif re.match(r"struct", obj['type']):
-    ///////////////////////////////////////////////////////////////////////////////
-    /// @brief Print ${th.make_type_name(n, tags, obj)} struct
-    /// @returns
-    ///     - ::${X}_RESULT_SUCCESS
-    ///     - ::${X}_RESULT_ERROR_INVALID_NULL_POINTER
-    ///         - `NULL == buffer`
-    ///     - ::${X}_RESULT_ERROR_INVALID_SIZE
-    ///         - `buff_size < out_size`
-    ${X}_APIEXPORT ${x}_result_t ${X}_APICALL ${th.make_func_name_with_prefix(f'{x}Print', obj['name'])}(const ${obj['type']} ${th.make_type_name(n, tags, obj)} params, char *buffer, const size_t buff_size, size_t *out_size);
-
-%endif
-%endfor # obj in spec['objects']
-%endfor
-
-%for tbl in th.get_pfncbtables(specs, meta, n, tags):
-%for obj in tbl['functions']:
 <%
-    name = th.make_pfncb_param_type(n, tags, obj)
+    api_types_funcs = tph.get_api_types_funcs(specs, meta, n, tags)
 %>
+## Declarations ###############################################################
+%for func in api_types_funcs:
 ///////////////////////////////////////////////////////////////////////////////
-/// @brief Print ${th.make_pfncb_param_type(n, tags, obj)} params struct
+/// @brief Print ${func.print_arg.type_name} ${func.print_arg.base_type}
 /// @returns
 ///     - ::${X}_RESULT_SUCCESS
-///     - ::${X}_RESULT_ERROR_INVALID_NULL_POINTER
-///         - `NULL == buffer`
 ///     - ::${X}_RESULT_ERROR_INVALID_SIZE
 ///         - `buff_size < out_size`
-${X}_APIEXPORT ${x}_result_t ${X}_APICALL ${th.make_func_name_with_prefix(f'{x}Print', name)}(const struct ${th.make_pfncb_param_type(n, tags, obj)} *params, char *buffer, const size_t buff_size, size_t *out_size);
-%endfor
+${X}_APIEXPORT ${x}_result_t ${X}_APICALL ${func.c_name}(${func.c_args});
+
 %endfor
 
 ///////////////////////////////////////////////////////////////////////////////
@@ -80,7 +49,6 @@ ${X}_APIEXPORT ${x}_result_t ${X}_APICALL ${th.make_func_name_with_prefix(f'{x}P
 ///     - ::${X}_RESULT_ERROR_INVALID_ENUMERATION
 ///     - ::${X}_RESULT_ERROR_INVALID_NULL_POINTER
 ///         - `NULL == params`
-///         - `NULL == buffer`
 ///     - ::${X}_RESULT_ERROR_INVALID_SIZE
 ///         - `buff_size < out_size`
 ${X}_APIEXPORT ${x}_result_t ${X}_APICALL ${x}PrintFunctionParams(enum ${x}_function_t function, const void *params, char *buffer, const size_t buff_size, size_t *out_size);