patrick/zephyr
1
0
Fork 0
Code Issues Pull requests Actions 7 Packages Projects Releases Wiki Activity

doc: add missing API content

Browse source 
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 <david.b.kinder@intel.com>
This commit is contained in:
David B. Kinder 2017-11-30 14:44:16 -08:00 committed by Anas Nashif
parent 967d8b5b59
commit 621ac8f84b
13 changed files with 231 additions and 41 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

15
.known-issues/doc/display.conf Normal file
View file

@ -0,0 +1,15 @@
#
# Display
#
#
# include
#
^(?P<filename>[-._/\w]+/doc/api/display_api.rst):(?P<lineno>[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]*\^

24
.known-issues/doc/kernel.conf Normal file
View file

@ -0,0 +1,24 @@
#
# Kernel
#
#
# include/kernel.h warnings
#
^(?P<filename>[-._/\w]+/doc/api/kernel_api.rst):(?P<lineno>[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]*\^

15
.known-issues/doc/misc.conf Normal file
View file

@ -0,0 +1,15 @@
#
# Display
#
#
# include
#
^(?P<filename>[-._/\w]+/doc/api/misc_api.rst):(?P<lineno>[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]*\^

2
doc/api/api.rst
View file

@ -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

103
doc/api/bluetooth.rst
View file

@ -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

20
doc/api/display_api.rst Normal file
View file

@ -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

5
doc/api/file_system.rst
View file

@ -3,6 +3,11 @@
File System APIs
#####################
.. comment
not documenting
.. doxygengroup:: file_system
File System Functions
*******************************

22
doc/api/io_interfaces.rst
View file

@ -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

22
doc/api/kernel_api.rst
View file

@ -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
***********************

27
doc/api/misc_api.rst Normal file
View file

@ -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

11
doc/api/networking.rst
View file

@ -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
********************

4
include/counter.h
View file

@ -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
* @{
*/

2
include/fs.h
View file

@ -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
* @{