Change api generator comment layout

How comments are laid out can have a significant effect on readability.
If we're to have 80column headers, then placing documentation comments
before a declaration line - rather than on the end of the same line -
can enable clang format to generate more readable headers without a
great change in the overall line length..

This might use more or less vertical space than the existing version,
since lines aren't off the right hand side. As an example:

```cpp
urLoaderConfigGetInfo(
    ur_loader_config_handle_t hLoaderConfig, ///< [in] handle of the loader config object
    ur_loader_config_info_t propName,        ///< [in] type of the info to retrieve
    size_t propSize,                         ///< [in] the number of bytes pointed to by pPropValue.
    void *pPropValue,                        ///< [out][optional][typename(propName, propSize)] array of bytes holding
                                             ///< the info.
                                             ///< If propSize is not equal to or greater than the real number of bytes
                                             ///< needed to return the info
                                             ///< then the ::UR_RESULT_ERROR_INVALID_SIZE error is returned and
                                             ///< pPropValue is not used.
    size_t *pPropSizeRet                     ///< [out][optional] pointer to the actual size in bytes of the queried propName.
);
```
->

```cpp
urLoaderConfigGetInfo(
  /// [in] handle of the loader config object
  ur_loader_config_handle_t hLoaderConfig,
  /// [in] type of the info to retrieve
  ur_loader_config_info_t propName,
  /// [in] the number of bytes pointed to by pPropValue.
  size_t propSize,
  /// [out][optional][typename(propName, propSize)] array of bytes holding the
  /// info. If propSize is not equal to or greater than the real number of bytes
  /// needed to return the info then the ::UR_RESULT_ERROR_INVALID_SIZE error is
  /// returned and pPropValue is not used.
  void *pPropValue,
  /// [out][optional] pointer to the actual size in bytes of the queried propName.
  size_t *pPropSizeRet
);
```
The comment and declaration for pPropValue takes fewer lines here, but
the shorter comments occupy more space.

Here is another example, where certain sequences can end up the same
length, but with a slightly more consistent appearance : enumerations
where the enumerator itself is long, and explicit values for the
enumerator declaration:

```cpp
    UR_FUNCTION_CONTEXT_SET_EXTENDED_DELETER =
      7,                      ///< Enumerator for ::urContextSetExtendedDeleter
```
->
```cpp
  /// Enumerator for ::urContextSetExtendedDeleter
  UR_FUNCTION_CONTEXT_SET_EXTENDED_DELETER = 7,
```

```
The total line length change for those files touched by the generator:
before:
```
  12411 include/ur_api.h
   1832 include/ur_ddi.h
   1564 scripts/templates/helper.py
   6818 source/adapters/null/ur_nullddi.cpp
   7650 source/loader/layers/tracing/ur_trcddi.cpp
  10658 source/loader/layers/validation/ur_valddi.cpp
   9173 source/loader/ur_ldrddi.cpp
   8706 source/loader/ur_libapi.cpp
   7390 source/ur_api.cpp
  66202 total
```
After:
```
  13051 include/ur_api.h
   1832 include/ur_ddi.h
   1564 scripts/templates/helper.py
   6986 source/adapters/null/ur_nullddi.cpp
   7671 source/loader/layers/tracing/ur_trcddi.cpp
  10153 source/loader/layers/validation/ur_valddi.cpp
   8986 source/loader/ur_ldrddi.cpp
   8770 source/loader/ur_libapi.cpp
   7637 source/ur_api.cpp
  66650 total
```

That's a less than 1% line length increase for generated code, so I
think this is a win.

Author: ldrumm

scripts/templates/__init__.py

@@ -1,8 +1,10 @@
 """
  Copyright (C) 2023 Intel Corporation
 
- Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM Exceptions.
+ Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM
+ Exceptions.
  See LICENSE.TXT
+
  SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
 """

scripts/templates/api.cpp.mako

@@ -11,8 +11,10 @@ from templates import helper as th
  *
  * Copyright (C) 2020 Intel Corporation
  *
- * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM Exceptions.
+ * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM
+ * Exceptions.
  * See LICENSE.TXT
+ *
  * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  * @file ${n}_api.cpp

scripts/templates/api.h.mako

@@ -11,8 +11,10 @@ from templates import helper as th
  *
  * Copyright (C) 2022 Intel Corporation
  *
- * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM Exceptions.
+ * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM
+ * Exceptions.
  * See LICENSE.TXT
+ *
  * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  * @file ${n}_api.h

scripts/templates/api_funcs.def.mako

@@ -12,8 +12,11 @@ from templates import helper as th
  *
  * Copyright (C) 2024 Intel Corporation
  *
- * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM Exceptions.
+ * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM
+ * Exceptions.
+ *
  * See LICENSE.TXT
+ *
  * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  * @file ${name}.def

scripts/templates/ddi.h.mako

@@ -11,8 +11,10 @@ from templates import helper as th
  *
  * Copyright (C) 2022 Intel Corporation
  *
- * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM Exceptions.
+ * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM
+ * Exceptions.
  * See LICENSE.TXT
+ *
  * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  * @file ${n}_ddi.h

scripts/templates/exp_feat.yml.mako

@@ -7,8 +7,10 @@ import datetime
 %>#
 # Copyright (C) ${year_now} Intel Corporation
 #
-# Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM Exceptions.
+# Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM
+# Exceptions.
 # See LICENSE.TXT
+#
 # SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 #
 # See YaML.md for syntax definition

scripts/templates/helper.py

@@ -825,8 +825,8 @@ def make_etor_lines(namespace, tags, obj, meta=None):
             prologue = "%s,"%(name)
 
         for line in split_line(subt(namespace, tags, item['desc'], True), 70):
-            lines.append("%s%s %s"%(append_ws(prologue, 48), "///<", line))
-            prologue = ""
+            lines.append(" /// %s" % line)
+        lines.append(prologue)
 
     lines += [
         "/// @cond",
@@ -877,8 +877,8 @@ def make_member_lines(namespace, tags, obj, prefix="", meta=None):
         prologue = "%s %s %s;"%(tname, name, array_suffix)
 
         for line in split_line(subt(namespace, tags, item['desc'], True), 70):
-            lines.append("%s%s %s"%(append_ws(prologue, 48), "///<", line))
-            prologue = ""
+            lines.append(" /// %s" % line)
+        lines.append(prologue)
     return lines
 
 """
@@ -926,8 +926,8 @@ def make_param_lines(namespace, tags, obj, decl=False, meta=None, format=["type"
         if "desc" in format:
             desc = item['desc']
             for line in split_line(subt(namespace, tags, desc, True), 70):
-                lines.append("%s///< %s"%(append_ws(prologue, 48), line))
-                prologue = ""
+                lines.append(" /// %s" % line)
+            lines.append(prologue)
         else:
             lines.append(prologue)
 

scripts/templates/ldrddi.cpp.mako

@@ -11,8 +11,10 @@ from templates import helper as th
  *
  * Copyright (C) 2022-2023 Intel Corporation
  *
- * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM Exceptions.
+ * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM
+ * Exceptions.
  * See LICENSE.TXT
+ *
  * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  * @file ${name}.cpp

scripts/templates/ldrddi.hpp.mako

@@ -11,8 +11,10 @@ from templates import helper as th
  *
  * Copyright (C) 2022-2023 Intel Corporation
  *
- * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM Exceptions.
+ * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM
+ * Exceptions.
  * See LICENSE.TXT
+ *
  * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  * @file ${name}.hpp

scripts/templates/libapi.cpp.mako

@@ -21,6 +21,7 @@ def define_dbg(obj, tags):
  *
  * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM Exceptions.
  * See LICENSE.TXT
+ *
  * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  * @file ${name}.cpp

scripts/templates/libddi.cpp.mako

@@ -11,8 +11,10 @@ from templates import helper as th
  *
  * Copyright (C) 2022 Intel Corporation
  *
- * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM Exceptions.
+ * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM
+ * Exceptions.
  * See LICENSE.TXT
+ *
  * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  * @file ${name}.cpp

scripts/templates/mockddi.cpp.mako

@@ -11,8 +11,10 @@ from templates import helper as th
  *
  * Copyright (C) 2024 Intel Corporation
  *
- * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM Exceptions.
+ * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM
+ * Exceptions.
  * See LICENSE.TXT
+
  * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  * @file ${name}.cpp

scripts/templates/optional_queries.h.mako

@@ -7,8 +7,10 @@ optional_queries = th.get_optional_queries(specs, namespace, tags)
  *
  * Copyright (C) 2024 Intel Corporation
  *
- * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM Exceptions.
+ * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM
+ * Exceptions.
  * See LICENSE.TXT
+ *
  * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  * @file ${filename}.h

scripts/templates/print.cpp.mako

@@ -11,8 +11,10 @@ from templates import print_helper as tph
  *
  * Copyright (C) 2023-2024 Intel Corporation
  *
- * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM Exceptions.
+ * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM
+ * Exceptions.
  * See LICENSE.TXT
+ *
  * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  * @file ${n}_print.cpp

scripts/templates/print.h.mako

@@ -11,8 +11,10 @@ from templates import print_helper as tph
  *
  * Copyright (C) 2023-2024 Intel Corporation
  *
- * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM Exceptions.
+ * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM
+ * Exceptions.
  * See LICENSE.TXT
+ *
  * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  * @file ${n}_print.h

scripts/templates/print.hpp.mako

@@ -11,8 +11,10 @@ from templates import helper as th
  *
  * Copyright (C) 2023-2024 Intel Corporation
  *
- * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM Exceptions.
+ * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM
+ * Exceptions.
  * See LICENSE.TXT
+ *
  * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  * @file ${name}.hpp

scripts/templates/print_helper.py

@@ -3,6 +3,7 @@
 
  Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM Exceptions.
  See LICENSE.TXT
+
  SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 
 A helper script for generating Printing API code and HTML documentation that aligns with the code.

scripts/templates/queue_api.cpp.mako

@@ -13,6 +13,7 @@ from templates import helper as th
  *
  * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM
  * Exceptions. See LICENSE.TXT
+ *
  * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  * @file ${name}.cpp
@@ -39,4 +40,4 @@ try {
     return exceptionToResult(std::current_exception());
 }
 %endfor
-}
+}

scripts/templates/queue_api.hpp.mako

@@ -13,6 +13,7 @@ from templates import helper as th
  *
  * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM
  * Exceptions. See LICENSE.TXT
+ *
  * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  * @file ${name}.hpp

scripts/templates/tools-info.hpp.mako

@@ -11,8 +11,10 @@ from templates import helper as th
  *
  * Copyright (C) 2023 Intel Corporation
  *
- * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM Exceptions.
+ * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM
+ * Exceptions.
  * See LICENSE.TXT
+ *
  * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  * @file ${name}.cpp

scripts/templates/trcddi.cpp.mako

@@ -10,8 +10,10 @@ from templates import helper as th
  *
  * Copyright (C) 2023 Intel Corporation
  *
- * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM Exceptions.
+ * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM
+ * Exceptions.
  * See LICENSE.TXT
+ *
  * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  * @file ${name}.cpp

scripts/templates/ur_interface_loader.cpp.mako

@@ -14,6 +14,7 @@ from templates import helper as th
 //
 // Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM
 // Exceptions. See LICENSE.TXT
+//
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//

scripts/templates/ur_interface_loader.hpp.mako

@@ -14,6 +14,7 @@ from templates import helper as th
 //
 // Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM
 // Exceptions. See LICENSE.TXT
+//
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//

scripts/templates/valddi.cpp.mako

@@ -13,8 +13,10 @@ from templates import helper as th
  *
  * Copyright (C) 2023-2024 Intel Corporation
  *
- * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM Exceptions.
+ * Part of the Unified-Runtime Project, under the Apache License v2.0 with LLVM
+ * Exceptions.
  * See LICENSE.TXT
+ *
  * SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
  *
  * @file ${name}.cpp