Fixing ndk reference doc link errors in a few headers:
hardware_buffer.h, sensor.h, trace.h, window.h
Bug:183022435, 183028131
Test: run 'm ndk' and regnerate reference docs, check the result is
correct
Change-Id: I7413453cd7f64f9585ed173d383708b25fcda5cb
diff --git a/include/android/sensor.h b/include/android/sensor.h
index 92b79c7..36fa326 100644
--- a/include/android/sensor.h
+++ b/include/android/sensor.h
@@ -428,6 +428,10 @@
} ADynamicSensorEvent;
typedef struct AAdditionalInfoEvent {
+ /**
+ * Event type, such as ASENSOR_ADDITIONAL_INFO_BEGIN, ASENSOR_ADDITIONAL_INFO_END and others.
+ * Refer to {@link ASENSOR_TYPE_ADDITIONAL_INFO} for the expected reporting behavior.
+ */
int32_t type;
int32_t serial;
union {
@@ -436,12 +440,22 @@
};
} AAdditionalInfoEvent;
+/**
+ * Information that describes a sensor event, refer to
+ * <a href="/reference/android/hardware/SensorEvent">SensorEvent</a> for additional
+ * documentation.
+ */
/* NOTE: changes to this struct has to be backward compatible */
typedef struct ASensorEvent {
int32_t version; /* sizeof(struct ASensorEvent) */
- int32_t sensor;
- int32_t type;
- int32_t reserved0;
+ int32_t sensor; /** The sensor that generates this event */
+ int32_t type; /** Sensor type for the event, such as {@link ASENSOR_TYPE_ACCELEROMETER}*/
+ int32_t reserved0; /** do not use */
+ /**
+ * The time in nanoseconds at which the event happened, and its behavior
+ * is identical to <a href="/reference/android/hardware/SensorEvent#timestamp">
+ * SensorEvent::timestamp</a> in Java API.
+ */
int64_t timestamp;
union {
union {
@@ -653,9 +667,10 @@
/**
* Destroy a direct channel
*
- * Destroy a direct channel previously created using {@link ASensorManager_createDirectChannel}.
- * The buffer used for creating direct channel does not get destroyed with
- * {@link ASensorManager_destroy} and has to be close or released separately.
+ * Destroy a direct channel previously created by using one of
+ * ASensorManager_create*DirectChannel() derivative functions.
+ * Note that the buffer used for creating the direct channel does not get destroyed with
+ * ASensorManager_destroyDirectChannel and has to be closed or released separately.
*
* Available since API level 26.
*
@@ -701,7 +716,7 @@
* \param channelId channel id (a positive integer) returned from
* {@link ASensorManager_createSharedMemoryDirectChannel} or
* {@link ASensorManager_createHardwareBufferDirectChannel}.
- *
+ * \param rate one of predefined ASENSOR_DIRECT_RATE_... that is supported by the sensor.
* \return positive token for success or negative error code.
*/
int ASensorManager_configureDirectReport(ASensorManager* manager,
@@ -718,7 +733,7 @@
* \param queue {@link ASensorEventQueue} for sensor event to be report to.
* \param sensor {@link ASensor} to be enabled.
* \param samplingPeriodUs sampling period of sensor in microseconds.
- * \param maxBatchReportLatencyus maximum time interval between two batch of sensor events are
+ * \param maxBatchReportLatencyUs maximum time interval between two batches of sensor events are
* delievered in microseconds. For sensor streaming, set to 0.
* \return 0 on success or a negative error code on failure.
*/
@@ -778,7 +793,7 @@
* Retrieve next available events from the queue to a specified event array.
*
* \param queue {@link ASensorEventQueue} to get events from
- * \param events pointer to an array of {@link ASensorEvents}.
+ * \param events pointer to an array of {@link ASensorEvent}.
* \param count max number of event that can be filled into array event.
* \return number of events returned on success; negative error code when
* no events are pending or an error has occurred.
@@ -798,7 +813,7 @@
* Request that {@link ASENSOR_TYPE_ADDITIONAL_INFO} events to be delivered on
* the given {@link ASensorEventQueue}.
*
- * Sensor data events are always delivered to the {@ASensorEventQueue}.
+ * Sensor data events are always delivered to the {@link ASensorEventQueue}.
*
* The {@link ASENSOR_TYPE_ADDITIONAL_INFO} events will be returned through
* {@link ASensorEventQueue_getEvents}. The client is responsible for checking
@@ -890,7 +905,7 @@
*
* \param sensor a {@link ASensor} to denote the sensor to be checked.
* \param channelType Channel type constant, either
- * {@ASENSOR_DIRECT_CHANNEL_TYPE_SHARED_MEMORY}
+ * {@link ASENSOR_DIRECT_CHANNEL_TYPE_SHARED_MEMORY}
* or {@link ASENSOR_DIRECT_CHANNEL_TYPE_HARDWARE_BUFFER}.
* \returns true if sensor supports the specified direct channel type.
*/
@@ -920,8 +935,8 @@
* sensor that generated the event.
*
* It is important to note that the value returned by {@link ASensor_getHandle} is not the same as
- * the value returned by the Java API {@link android.hardware.Sensor#getId} and no mapping exists
- * between the values.
+ * the value returned by the Java API <a href="/reference/android/hardware/Sensor#getId()">
+ * android.hardware.Sensor's getId()</a> and no mapping exists between the values.
*
* Available since API level 29.
*/
diff --git a/include/android/sharedmem.h b/include/android/sharedmem.h
index 7994aa9..e0a8045 100644
--- a/include/android/sharedmem.h
+++ b/include/android/sharedmem.h
@@ -59,9 +59,10 @@
*
* Use close() to release the shared memory region.
*
- * Use {@link android.os.ParcelFileDescriptor} to pass the file descriptor to
- * another process. File descriptors may also be sent to other processes over a Unix domain
- * socket with sendmsg and SCM_RIGHTS. See sendmsg(3) and cmsg(3) man pages for more information.
+ * Use <a href="/reference/android/os/ParcelFileDescriptor">android.os.ParcelFileDescriptor</a>
+ * to pass the file descriptor to another process. File descriptors may also be sent to other
+ * processes over a Unix domain socket with sendmsg and SCM_RIGHTS. See sendmsg(3) and
+ * cmsg(3) man pages for more information.
*
* If you intend to share this file descriptor with a child process after
* calling exec(3), note that you will need to use fcntl(2) with FD_SETFD
@@ -71,7 +72,8 @@
*
* \param name an optional name.
* \param size size of the shared memory region
- * \return file descriptor that denotes the shared memory; -1 and sets errno on failure, or -EINVAL if the error is that size was 0.
+ * \return file descriptor that denotes the shared memory;
+ * -1 and sets errno on failure, or -EINVAL if the error is that size was 0.
*/
int ASharedMemory_create(const char *name, size_t size) __INTRODUCED_IN(26);
diff --git a/include/android/thermal.h b/include/android/thermal.h
index 0ea13d3..32580ba 100644
--- a/include/android/thermal.h
+++ b/include/android/thermal.h
@@ -60,6 +60,10 @@
extern "C" {
#endif
+/**
+ * Thermal status used in function {@link AThermal_getCurrentThermalStatus} and
+ * {@link AThermal_StatusCallback}.
+ */
enum AThermalStatus {
/** Error in thermal status. */
ATHERMAL_STATUS_ERROR = -1,
@@ -194,10 +198,10 @@
*
* The value returned is a non-negative float that represents how much of the thermal envelope
* is in use (or is forecasted to be in use). A value of 1.0 indicates that the device is
- * (or will be) throttled at {@link #THERMAL_STATUS_SEVERE}. Such throttling can affect the
+ * (or will be) throttled at {@link #ATHERMAL_STATUS_SEVERE}. Such throttling can affect the
* CPU, GPU, and other subsystems. Values may exceed 1.0, but there is no implied mapping
* to specific thermal levels beyond that point. This means that values greater than 1.0
- * may correspond to {@link #THERMAL_STATUS_SEVERE}, but may also represent heavier throttling.
+ * may correspond to {@link #ATHERMAL_STATUS_SEVERE}, but may also represent heavier throttling.
*
* A value of 0.0 corresponds to a fixed distance from 1.0, but does not correspond to any
* particular thermal status or temperature. Values on (0.0, 1.0] may be expected to scale
diff --git a/include/android/trace.h b/include/android/trace.h
index dcefffb..d11158b 100644
--- a/include/android/trace.h
+++ b/include/android/trace.h
@@ -91,7 +91,7 @@
*
* Available since API level 29.
*
- * \param methodName The method name to appear in the trace.
+ * \param sectionName The method name to appear in the trace.
* \param cookie Unique identifier for distinguishing simultaneous events
*/
void ATrace_endAsyncSection(const char* sectionName, int32_t cookie) __INTRODUCED_IN(29);
diff --git a/include/android/window.h b/include/android/window.h
index 436bf3a..c144864 100644
--- a/include/android/window.h
+++ b/include/android/window.h
@@ -103,8 +103,9 @@
* bar) while this window is displayed. This allows the window to
* use the entire display space for itself -- the status bar will
* be hidden when an app window with this flag set is on the top
- * layer. A fullscreen window will ignore a value of {@link
- * AWINDOW_SOFT_INPUT_ADJUST_RESIZE}; the window will stay
+ * layer. A fullscreen window will ignore a value of
+ * <a href="/reference/android/view/WindowManager.LayoutParams#SOFT_INPUT_ADJUST_RESIZE">
+ * SOFT_INPUT_ADJUST_RESIZE</a>; the window will stay
* fullscreen and will not resize.
*/
AWINDOW_FLAG_FULLSCREEN = 0x00000400,
diff --git a/libs/nativewindow/include/android/hardware_buffer.h b/libs/nativewindow/include/android/hardware_buffer.h
index 20a1f74..d93a84c 100644
--- a/libs/nativewindow/include/android/hardware_buffer.h
+++ b/libs/nativewindow/include/android/hardware_buffer.h
@@ -164,45 +164,56 @@
* Buffer usage flags, specifying how the buffer will be accessed.
*/
enum AHardwareBuffer_UsageFlags {
- /// The buffer will never be locked for direct CPU reads using the
- /// AHardwareBuffer_lock() function. Note that reading the buffer
- /// using OpenGL or Vulkan functions or memory mappings is still
- /// allowed.
+ /**
+ * The buffer will never be locked for direct CPU reads using the
+ * AHardwareBuffer_lock() function. Note that reading the buffer
+ * using OpenGL or Vulkan functions or memory mappings is still
+ * allowed.
+ */
AHARDWAREBUFFER_USAGE_CPU_READ_NEVER = 0UL,
- /// The buffer will sometimes be locked for direct CPU reads using
- /// the AHardwareBuffer_lock() function. Note that reading the
- /// buffer using OpenGL or Vulkan functions or memory mappings
- /// does not require the presence of this flag.
+ /**
+ * The buffer will sometimes be locked for direct CPU reads using
+ * the AHardwareBuffer_lock() function. Note that reading the
+ * buffer using OpenGL or Vulkan functions or memory mappings
+ * does not require the presence of this flag.
+ */
AHARDWAREBUFFER_USAGE_CPU_READ_RARELY = 2UL,
- /// The buffer will often be locked for direct CPU reads using
- /// the AHardwareBuffer_lock() function. Note that reading the
- /// buffer using OpenGL or Vulkan functions or memory mappings
- /// does not require the presence of this flag.
+ /**
+ * The buffer will often be locked for direct CPU reads using
+ * the AHardwareBuffer_lock() function. Note that reading the
+ * buffer using OpenGL or Vulkan functions or memory mappings
+ * does not require the presence of this flag.
+ */
AHARDWAREBUFFER_USAGE_CPU_READ_OFTEN = 3UL,
- /// CPU read value mask.
+
+ /** CPU read value mask. */
AHARDWAREBUFFER_USAGE_CPU_READ_MASK = 0xFUL,
-
- /// The buffer will never be locked for direct CPU writes using the
- /// AHardwareBuffer_lock() function. Note that writing the buffer
- /// using OpenGL or Vulkan functions or memory mappings is still
- /// allowed.
+ /**
+ * The buffer will never be locked for direct CPU writes using the
+ * AHardwareBuffer_lock() function. Note that writing the buffer
+ * using OpenGL or Vulkan functions or memory mappings is still
+ * allowed.
+ */
AHARDWAREBUFFER_USAGE_CPU_WRITE_NEVER = 0UL << 4,
- /// The buffer will sometimes be locked for direct CPU writes using
- /// the AHardwareBuffer_lock() function. Note that writing the
- /// buffer using OpenGL or Vulkan functions or memory mappings
- /// does not require the presence of this flag.
+ /**
+ * The buffer will sometimes be locked for direct CPU writes using
+ * the AHardwareBuffer_lock() function. Note that writing the
+ * buffer using OpenGL or Vulkan functions or memory mappings
+ * does not require the presence of this flag.
+ */
AHARDWAREBUFFER_USAGE_CPU_WRITE_RARELY = 2UL << 4,
- /// The buffer will often be locked for direct CPU writes using
- /// the AHardwareBuffer_lock() function. Note that writing the
- /// buffer using OpenGL or Vulkan functions or memory mappings
- /// does not require the presence of this flag.
+ /**
+ * The buffer will often be locked for direct CPU writes using
+ * the AHardwareBuffer_lock() function. Note that writing the
+ * buffer using OpenGL or Vulkan functions or memory mappings
+ * does not require the presence of this flag.
+ */
AHARDWAREBUFFER_USAGE_CPU_WRITE_OFTEN = 3UL << 4,
- /// CPU write value mask.
+ /** CPU write value mask. */
AHARDWAREBUFFER_USAGE_CPU_WRITE_MASK = 0xFUL << 4,
-
- /// The buffer will be read from by the GPU as a texture.
+ /** The buffer will be read from by the GPU as a texture. */
AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE = 1UL << 8,
- /// The buffer will be written to by the GPU as a framebuffer attachment.
+ /** The buffer will be written to by the GPU as a framebuffer attachment.*/
AHARDWAREBUFFER_USAGE_GPU_FRAMEBUFFER = 1UL << 9,
/**
* The buffer will be written to by the GPU as a framebuffer
@@ -237,7 +248,7 @@
* buffers are expected to behave.
*/
AHARDWAREBUFFER_USAGE_PROTECTED_CONTENT = 1UL << 14,
- /// The buffer will be read by a hardware video encoder.
+ /** The buffer will be read by a hardware video encoder. */
AHARDWAREBUFFER_USAGE_VIDEO_ENCODE = 1UL << 16,
/**
* The buffer will be used for direct writes from sensors.