From 621ac8f84ba839b8fd91667afb0334638a8dc938 Mon Sep 17 00:00:00 2001 From: "David B. Kinder" Date: Thu, 30 Nov 2017 14:44:16 -0800 Subject: [PATCH] doc: add missing API content Some API material (from doxygen comments) wasn't included in the generated documentation because there was no doxygengroup Sphinx directive to display them. This PR add content into appropriate places in existing documentation (e.g., Bluetooth Cryptography APIs into the Bluetooth API doc) and creates two new collections for Display and Miscellaneous APIs. Comments added to the .rst files to mention doxygengroups that are intentionally excluded (because they're organizational groups containing subgroups that are included). Sorted the Bluetooth API list, mostly. Fixed a couple doxygen group titles defined in the include files, and added a few patterns to filter new "expected" errors from the document generation process. Legacy and deprecated APIs remain left out, as intended: http_legacy (net/http_legacy.h) spi_interface_legacy (spi_legacy.h) zoap (net/zoap.h) fixes: Issue #5051 Signed-off-by: David B. Kinder --- .known-issues/doc/display.conf | 15 +++++ .known-issues/doc/kernel.conf | 24 ++++++++ .known-issues/doc/misc.conf | 15 +++++ doc/api/api.rst | 2 + doc/api/bluetooth.rst | 103 +++++++++++++++++++++------------ doc/api/display_api.rst | 20 +++++++ doc/api/file_system.rst | 5 ++ doc/api/io_interfaces.rst | 22 +++++++ doc/api/kernel_api.rst | 22 +++++++ doc/api/misc_api.rst | 27 +++++++++ doc/api/networking.rst | 11 ++++ include/counter.h | 4 +- include/fs.h | 2 +- 13 files changed, 231 insertions(+), 41 deletions(-) create mode 100644 .known-issues/doc/display.conf create mode 100644 .known-issues/doc/kernel.conf create mode 100644 .known-issues/doc/misc.conf create mode 100644 doc/api/display_api.rst create mode 100644 doc/api/misc_api.rst diff --git a/.known-issues/doc/display.conf b/.known-issues/doc/display.conf new file mode 100644 index 0000000000..e8142a77ba --- /dev/null +++ b/.known-issues/doc/display.conf @@ -0,0 +1,15 @@ +# +# Display +# +# +# include +# +^(?P[-._/\w]+/doc/api/display_api.rst):(?P[0-9]+): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+] +^[ \t]* +^[ \t]*\^ +^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+] +^[ \t]* +^[ \t]*\^ +^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected end of definition. \[error at [0-9]+] +^.*mb_image.__unnamed__ +^[- \t]*\^ diff --git a/.known-issues/doc/kernel.conf b/.known-issues/doc/kernel.conf new file mode 100644 index 0000000000..bababb9f89 --- /dev/null +++ b/.known-issues/doc/kernel.conf @@ -0,0 +1,24 @@ +# +# Kernel +# +# +# include/kernel.h warnings +# +^(?P[-._/\w]+/doc/api/kernel_api.rst):(?P[0-9]+): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+] +^[ \t]* +^[ \t]*\^ +^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+] +^[ \t]* +^[ \t]*\^ +^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+] +^[ \t]* +^[ \t]*\^ +^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+] +^[ \t]* +^[ \t]*\^ +^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+] +^[ \t]* +^[ \t]*\^ +^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected end of definition. \[error at [0-9]+] +^.*k_poll_event.__unnamed__ +^[- \t]*\^ diff --git a/.known-issues/doc/misc.conf b/.known-issues/doc/misc.conf new file mode 100644 index 0000000000..3f76b0c0b2 --- /dev/null +++ b/.known-issues/doc/misc.conf @@ -0,0 +1,15 @@ +# +# Display +# +# +# include +# +^(?P[-._/\w]+/doc/api/misc_api.rst):(?P[0-9]+): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+] +^[ \t]* +^[ \t]*\^ +^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected identifier in nested name. \[error at [0-9]+] +^[ \t]* +^[ \t]*\^ +^(?P=filename):(?P=lineno): WARNING: Invalid definition: Expected end of definition. \[error at [0-9]+] +^.*json_obj_descr.__unnamed__ +^[- \t]*\^ diff --git a/doc/api/api.rst b/doc/api/api.rst index 7ca1344860..f26ae5523c 100644 --- a/doc/api/api.rst +++ b/doc/api/api.rst @@ -23,3 +23,5 @@ The Zephyr APIs are used the same way on all SoCs and boards. io_interfaces.rst power_management_api file_system + display_api + misc_api diff --git a/doc/api/bluetooth.rst b/doc/api/bluetooth.rst index e61897761d..4172eb0aba 100644 --- a/doc/api/bluetooth.rst +++ b/doc/api/bluetooth.rst @@ -15,26 +15,12 @@ of the Bluetooth functionality is build-time selectable. E.g. any connection-related APIs require :option:`CONFIG_BT_CONN` and any BR/EDR (Bluetooth Classic) APIs require :option:`CONFIG_BT_BREDR`. -Generic Access Profile (GAP) -**************************** +.. comment + not documenting + .. doxygengroup:: bluetooth -.. doxygengroup:: bt_gap - :project: Zephyr - -Connection Management -********************* - -.. doxygengroup:: bt_conn - :project: Zephyr - -Generic Attribute Profile (GATT) -******************************** - -.. doxygengroup:: bt_gatt - :project: Zephyr - -Mesh Profile -************ +Bluetooth Mesh Profile +********************** .. doxygengroup:: bt_mesh :project: Zephyr @@ -57,6 +43,12 @@ Bluetooth Mesh Configuration Server Model .. doxygengroup:: bt_mesh_cfg_srv :project: Zephyr +Bluetooth Mesh Health Client Model +================================== + +.. doxygengroup:: bt_mesh_health_cli + :project: Zephyr + Bluetooth Mesh Health Server Model ================================== @@ -75,23 +67,16 @@ Bluetooth Mesh Proxy .. doxygengroup:: bt_mesh_proxy :project: Zephyr +Connection Management +********************* -Universal Unique Identifiers (UUIDs) -************************************ - -.. doxygengroup:: bt_uuid +.. doxygengroup:: bt_conn :project: Zephyr -Logical Link Control and Adaptation Protocol (L2CAP) -**************************************************** +Cryptography +************ -.. doxygengroup:: bt_l2cap - :project: Zephyr - -Serial Port Emulation (RFCOMM) -****************************** - -.. doxygengroup:: bt_rfcomm +.. doxygengroup:: bt_crypto :project: Zephyr Data Buffers @@ -100,16 +85,16 @@ Data Buffers .. doxygengroup:: bt_buf :project: Zephyr -Persistent Storage -****************** +Generic Access Profile (GAP) +**************************** -.. doxygengroup:: bt_storage +.. doxygengroup:: bt_gap :project: Zephyr -HCI Drivers -*********** +Generic Attribute Profile (GATT) +******************************** -.. doxygengroup:: bt_hci_driver +.. doxygengroup:: bt_gatt :project: Zephyr HCI RAW channel @@ -122,3 +107,45 @@ are sent and received by the Bluetooth HCI driver. .. doxygengroup:: hci_raw :project: Zephyr + +HCI Drivers +*********** + +.. doxygengroup:: bt_hci_driver + :project: Zephyr + +Hands Free Profile (HFP) +************************ + +.. doxygengroup:: bt_hfp + :project: Zephyr + +Logical Link Control and Adaptation Protocol (L2CAP) +**************************************************** + +.. doxygengroup:: bt_l2cap + :project: Zephyr + +Persistent Storage +****************** + +.. doxygengroup:: bt_storage + :project: Zephyr + +Serial Port Emulation (RFCOMM) +****************************** + +.. doxygengroup:: bt_rfcomm + :project: Zephyr + +Service Discovery Protocol (SDP) +******************************** + +.. doxygengroup:: bt_sdp + :project: Zephyr + +Universal Unique Identifiers (UUIDs) +************************************ + +.. doxygengroup:: bt_uuid + :project: Zephyr diff --git a/doc/api/display_api.rst b/doc/api/display_api.rst new file mode 100644 index 0000000000..364a4f9c79 --- /dev/null +++ b/doc/api/display_api.rst @@ -0,0 +1,20 @@ +.. _display_api: + +Display Interface APIs +###################### + +.. comment + not documenting + .. doxygengroup:: display_interfaces + +Grove LCD Display +***************** + +.. doxygengroup:: grove_display + :project: Zephyr + +BBC micro:bit Display +********************* + +.. doxygengroup:: mb_display + :project: Zephyr diff --git a/doc/api/file_system.rst b/doc/api/file_system.rst index 9a7597f6db..7f036cf8f0 100644 --- a/doc/api/file_system.rst +++ b/doc/api/file_system.rst @@ -3,6 +3,11 @@ File System APIs ##################### + +.. comment + not documenting + .. doxygengroup:: file_system + File System Functions ******************************* diff --git a/doc/api/io_interfaces.rst b/doc/api/io_interfaces.rst index 59bc1b16f1..bd61d72ce3 100644 --- a/doc/api/io_interfaces.rst +++ b/doc/api/io_interfaces.rst @@ -8,12 +8,22 @@ Input / Output Driver APIs :local: :backlinks: top +.. comment + not documenting + .. doxygengroup:: io_interfaces + ADC Interface ************* .. doxygengroup:: adc_interface :project: Zephyr +DMA Interface +************* + +.. doxygengroup:: DMA_interface + :project: Zephyr + GPIO Interface ************** @@ -72,8 +82,20 @@ UART Interface .. doxygengroup:: uart_interface :project: Zephyr +Flash Interface +*************** + +.. doxygengroup:: flash_interface + :project: Zephyr + Sensor Interface **************** .. doxygengroup:: sensor_interface :project: Zephyr + +Counter Interface +***************** + +.. doxygengroup:: counter_interface + :project: Zephyr diff --git a/doc/api/kernel_api.rst b/doc/api/kernel_api.rst index 367e4b0ca0..d1081f4085 100644 --- a/doc/api/kernel_api.rst +++ b/doc/api/kernel_api.rst @@ -14,6 +14,10 @@ as described in the :ref:`kernel`. :local: :backlinks: top +.. comment + not documenting + .. doxygengroup:: kernel_apis + Threads ******* @@ -145,6 +149,12 @@ data items. .. doxygengroup:: stack_apis :project: Zephyr +Queues +****** + +.. doxygengroup:: queue_apis + :project: Zephyr + Message Queues ************** @@ -175,6 +185,12 @@ variable-size chunks of data, in whole or in part. .. doxygengroup:: pipe_apis :project: Zephyr +Asynchronous Polling +******************** + +.. doxygengroup:: poll_apis + :project: Zephyr + Interrupt Service Routines (ISRs) ********************************* @@ -198,6 +214,12 @@ The atomic services enable multiple threads and ISRs to read and modify .. doxygengroup:: atomic_apis :project: Zephyr +Profiling +********* + +.. doxygengroup:: profiling_apis + :project: Zephyr + Floating Point Services *********************** diff --git a/doc/api/misc_api.rst b/doc/api/misc_api.rst new file mode 100644 index 0000000000..b446b639e1 --- /dev/null +++ b/doc/api/misc_api.rst @@ -0,0 +1,27 @@ +.. _misc_api: + +Miscellaneous APIs +################## + +.. comment + not documenting + .. doxygengroup:: checksum + .. doxygengroup:: structured_data + +Checksum APIs +************* + +CRC16 +===== + +.. doxygengroup:: crc16 + :project: Zephyr + +Structured Data APIs +******************** + +JSON +==== + +.. doxygengroup:: json + :project: Zephyr diff --git a/doc/api/networking.rst b/doc/api/networking.rst index 871714b55f..85194b513a 100644 --- a/doc/api/networking.rst +++ b/doc/api/networking.rst @@ -13,6 +13,11 @@ depends on relevant Kconfig options. For instance IPv6 related APIs will not be present if :option:`CONFIG_NET_IPV6` has not been selected. +.. comment + not documenting + .. doxygengroup:: networking + .. doxygengroup:: arp + Network core helpers ******************** @@ -97,6 +102,12 @@ UDP .. doxygengroup:: udp :project: Zephyr +Hostname Configuration Library +****************************** + +.. doxygengroup:: net_hostname + :project: Zephyr + Network technologies ******************** diff --git a/include/counter.h b/include/counter.h index eee070cc7d..a5d192a2e1 100644 --- a/include/counter.h +++ b/include/counter.h @@ -13,8 +13,8 @@ #define __COUNTER_H__ /** - * @brief COUNTER Interface - * @defgroup counter_interface COUNTER Interface + * @brief Counter Interface + * @defgroup counter_interface Counter Interface * @ingroup io_interfaces * @{ */ diff --git a/include/fs.h b/include/fs.h index 625243a409..c2fea3300d 100644 --- a/include/fs.h +++ b/include/fs.h @@ -33,7 +33,7 @@ enum fs_dir_entry_type { */ /** - * @brief File System Functions + * @brief File System Data Structures * @defgroup data_structures File System Data Structures * @ingroup file_system * @{