[Objective-C API] Add support for documentation generation (#7999)

Adding support for generating API documentation with the Jazzy tool.
It's a manual process now, but we can eventually make it a part of the release pipeline.

objectivec/docs/docs.readme.md

@@ -0,0 +1,5 @@
+# ONNX Runtime Objective-C API
+
+ONNX Runtime provides an Objective-C API.
+
+It can be used from Objective-C/C++ or Swift with a bridging header.

objectivec/docs/jazzy_config.yaml

@@ -0,0 +1,13 @@
+module: ONNX Runtime Objective-C API
+author: ONNX Runtime Authors
+author_url: https://www.onnxruntime.ai
+github_url: https://github.com/microsoft/onnxruntime
+
+objc: true
+umbrella_header: ../include/onnxruntime.h
+framework_root: ..
+
+readme: ./docs.readme.md
+
+hide_documentation_coverage: true
+undocumented_text: ""

objectivec/docs/readme.md

@@ -0,0 +1,17 @@
+# Objective-C API Documentation
+
+The API should be documented with comments in the [public header files](../include).
+
+## Documentation Generation
+
+The [Jazzy](https://github.com/realm/jazzy) tool is used to generate documentation from the code.
+
+For example, to generate documentation for a release version, from the repo root, run:
+
+```bash
+jazzy --config objectivec/docs/jazzy_config.yaml --output <output directory> --module-version $(cat VERSION_NUMBER)
+```
+
+The generated documentation website files will be in `<output directory>`.
+
+[docs.readme.md](./docs.readme.md) contains content for the main page of the generated documentation website.

objectivec/include/ort_coreml_execution_provider.h

@@ -43,7 +43,7 @@ BOOL ORTIsCoreMLExecutionProviderAvailable(void);
  * decreasing priority.
  *
  * @param options The CoreML execution provider configuration options.
- * @param[out] error Optional error information set if an error occurs.
+ * @param error Optional error information set if an error occurs.
  * @return Whether the provider was enabled successfully.
  */
 - (BOOL)appendCoreMLExecutionProviderWithOptions:(ORTCoreMLExecutionProviderOptions*)options

objectivec/include/ort_env.h

@@ -18,7 +18,7 @@ NS_ASSUME_NONNULL_BEGIN
  * Creates an ORT Environment.
  *
  * @param loggingLevel The environment logging level.
- * @param[out] error Optional error information set if an error occurs.
+ * @param error Optional error information set if an error occurs.
  * @return The instance, or nil if an error occurs.
  */
 - (nullable instancetype)initWithLoggingLevel:(ORTLoggingLevel)loggingLevel

objectivec/include/ort_session.h

@@ -25,7 +25,7 @@ NS_ASSUME_NONNULL_BEGIN
  * @param env The ORT Environment instance.
  * @param path The path to the ONNX model.
  * @param sessionOptions Optional session configuration options.
- * @param[out] error Optional error information set if an error occurs.
+ * @param error Optional error information set if an error occurs.
  * @return The instance, or nil if an error occurs.
  */
 - (nullable instancetype)initWithEnv:(ORTEnv*)env
@@ -40,7 +40,7 @@ NS_ASSUME_NONNULL_BEGIN
  * @param inputs Dictionary of input names to input ORT values.
  * @param outputs Dictionary of output names to output ORT values.
  * @param runOptions Optional run configuration options.
- * @param[out] error Optional error information set if an error occurs.
+ * @param error Optional error information set if an error occurs.
  * @return Whether the model was run successfully.
  */
 - (BOOL)runWithInputs:(NSDictionary<NSString*, ORTValue*>*)inputs
@@ -55,7 +55,7 @@ NS_ASSUME_NONNULL_BEGIN
  * @param inputs Dictionary of input names to input ORT values.
  * @param outputNames Set of output names.
  * @param runOptions Optional run configuration options.
- * @param[out] error Optional error information set if an error occurs.
+ * @param error Optional error information set if an error occurs.
  * @return A dictionary of output names to output ORT values with the outputs
  *         requested in `outputNames`, or nil if an error occurs.
  */
@@ -67,7 +67,7 @@ NS_ASSUME_NONNULL_BEGIN
 /**
  * Gets the model's input names.
  *
- * @param[out] error Optional error information set if an error occurs.
+ * @param error Optional error information set if an error occurs.
  * @return An array of input names, or nil if an error occurs.
  */
 - (nullable NSArray<NSString*>*)inputNamesWithError:(NSError**)error;
@@ -75,7 +75,7 @@ NS_ASSUME_NONNULL_BEGIN
 /**
  * Gets the model's overridable initializer names.
  *
- * @param[out] error Optional error information set if an error occurs.
+ * @param error Optional error information set if an error occurs.
  * @return An array of overridable initializer names, or nil if an error occurs.
  */
 - (nullable NSArray<NSString*>*)overridableInitializerNamesWithError:(NSError**)error;
@@ -83,7 +83,7 @@ NS_ASSUME_NONNULL_BEGIN
 /**
  * Gets the model's output names.
  *
- * @param[out] error Optional error information set if an error occurs.
+ * @param error Optional error information set if an error occurs.
  * @return An array of output names, or nil if an error occurs.
  */
 - (nullable NSArray<NSString*>*)outputNamesWithError:(NSError**)error;
@@ -100,7 +100,7 @@ NS_ASSUME_NONNULL_BEGIN
 /**
  * Creates session configuration options.
  *
- * @param[out] error Optional error information set if an error occurs.
+ * @param error Optional error information set if an error occurs.
  * @return The instance, or nil if an error occurs.
  */
 - (nullable instancetype)initWithError:(NSError**)error NS_SWIFT_NAME(init());
@@ -110,7 +110,7 @@ NS_ASSUME_NONNULL_BEGIN
  * A value of 0 means ORT will pick a default value.
  *
  * @param intraOpNumThreads The number of threads.
- * @param[out] error Optional error information set if an error occurs.
+ * @param error Optional error information set if an error occurs.
  * @return Whether the option was set successfully.
  */
 - (BOOL)setIntraOpNumThreads:(int)intraOpNumThreads
@@ -120,7 +120,7 @@ NS_ASSUME_NONNULL_BEGIN
  * Sets the graph optimization level.
  *
  * @param graphOptimizationLevel The graph optimization level.
- * @param[out] error Optional error information set if an error occurs.
+ * @param error Optional error information set if an error occurs.
  * @return Whether the option was set successfully.
  */
 - (BOOL)setGraphOptimizationLevel:(ORTGraphOptimizationLevel)graphOptimizationLevel
@@ -130,7 +130,7 @@ NS_ASSUME_NONNULL_BEGIN
  * Sets the path to which the optimized model file will be saved.
  *
  * @param optimizedModelFilePath The optimized model file path.
- * @param[out] error Optional error information set if an error occurs.
+ * @param error Optional error information set if an error occurs.
  * @return Whether the option was set successfully.
  */
 - (BOOL)setOptimizedModelFilePath:(NSString*)optimizedModelFilePath
@@ -140,7 +140,7 @@ NS_ASSUME_NONNULL_BEGIN
  * Sets the session log ID.
  *
  * @param logID The log ID.
- * @param[out] error Optional error information set if an error occurs.
+ * @param error Optional error information set if an error occurs.
  * @return Whether the option was set successfully.
  */
 - (BOOL)setLogID:(NSString*)logID
@@ -150,7 +150,7 @@ NS_ASSUME_NONNULL_BEGIN
  * Sets the session log severity level.
  *
  * @param loggingLevel The log severity level.
- * @param[out] error Optional error information set if an error occurs.
+ * @param error Optional error information set if an error occurs.
  * @return Whether the option was set successfully.
  */
 - (BOOL)setLogSeverityLevel:(ORTLoggingLevel)loggingLevel
@@ -164,7 +164,7 @@ NS_ASSUME_NONNULL_BEGIN
  *
  * @param key The key.
  * @param value The value.
- * @param[out] error Optional error information set if an error occurs.
+ * @param error Optional error information set if an error occurs.
  * @return Whether the option was set successfully.
  */
 - (BOOL)addConfigEntryWithKey:(NSString*)key
@@ -183,7 +183,7 @@ NS_ASSUME_NONNULL_BEGIN
 /**
  * Creates run configuration options.
  *
- * @param[out] error Optional error information set if an error occurs.
+ * @param error Optional error information set if an error occurs.
  * @return The instance, or nil if an error occurs.
  */
 - (nullable instancetype)initWithError:(NSError**)error NS_SWIFT_NAME(init());
@@ -192,7 +192,7 @@ NS_ASSUME_NONNULL_BEGIN
  * Sets the run log tag.
  *
  * @param logTag The log tag.
- * @param[out] error Optional error information set if an error occurs.
+ * @param error Optional error information set if an error occurs.
  * @return Whether the option was set successfully.
  */
 - (BOOL)setLogTag:(NSString*)logTag
@@ -202,7 +202,7 @@ NS_ASSUME_NONNULL_BEGIN
  * Sets the run log severity level.
  *
  * @param loggingLevel The log severity level.
- * @param[out] error Optional error information set if an error occurs.
+ * @param error Optional error information set if an error occurs.
  * @return Whether the option was set successfully.
  */
 - (BOOL)setLogSeverityLevel:(ORTLoggingLevel)loggingLevel
@@ -216,7 +216,7 @@ NS_ASSUME_NONNULL_BEGIN
  *
  * @param key The key.
  * @param value The value.
- * @param[out] error Optional error information set if an error occurs.
+ * @param error Optional error information set if an error occurs.
  * @return Whether the option was set successfully.
  */
 - (BOOL)addConfigEntryWithKey:(NSString*)key

objectivec/include/ort_value.h

@@ -24,7 +24,7 @@ NS_ASSUME_NONNULL_BEGIN
  * @param tensorData The tensor data.
  * @param elementType The tensor element data type.
  * @param shape The tensor shape.
- * @param[out] error Optional error information set if an error occurs.
+ * @param error Optional error information set if an error occurs.
  * @return The instance, or nil if an error occurs.
  */
 - (nullable instancetype)initWithTensorData:(NSMutableData*)tensorData
@@ -35,7 +35,7 @@ NS_ASSUME_NONNULL_BEGIN
 /**
  * Gets the type information.
  *
- * @param[out] error Optional error information set if an error occurs.
+ * @param error Optional error information set if an error occurs.
  * @return The type information, or nil if an error occurs.
  */
 - (nullable ORTValueTypeInfo*)typeInfoWithError:(NSError**)error;
@@ -44,7 +44,7 @@ NS_ASSUME_NONNULL_BEGIN
  * Gets the tensor type and shape information.
  * This assumes that the value is a tensor.
  *
- * @param[out] error Optional error information set if an error occurs.
+ * @param error Optional error information set if an error occurs.
  * @return The tensor type and shape information, or nil if an error occurs.
  */
 - (nullable ORTTensorTypeAndShapeInfo*)tensorTypeAndShapeInfoWithError:(NSError**)error;
@@ -53,7 +53,12 @@ NS_ASSUME_NONNULL_BEGIN
  * Gets the tensor data.
  * This assumes that the value is a tensor.
  *
- * @param[out] error Optional error information set if an error occurs.
+ * This returns the value's underlying data directly, not a copy of it.
+ * The memory's lifetime may be tied to this value, i.e., if it was allocated
+ * by ORT. On the other hand, the memory's lifetime is independent of the value
+ * if the value was created with user-provided data.
+ *
+ * @param error Optional error information set if an error occurs.
  * @return The tensor data, or nil if an error occurs.
  */
 - (nullable NSMutableData*)tensorDataWithError:(NSError**)error;