Skip to contentSkip to conversation

Port text docs to RST

PATCH In review Bastien Nocera 2 participants 9 messages Jan 20

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

v2 cover Port text docs to RST

So they can be integrated into our upcoming HTML docs. See:
https://hadess.github.io/bluez/
for a preview.

Changes since v1:
- Fix distcheck

Bastien Nocera (7):
doc: Port assigned-numbers.txt to RST
doc: Port thermometer-api.txt to RST
doc: Port security-bugs.txt to RST
doc: Port coding-style.txt to RST
doc: Port sap-api.txt to RST
doc: Port maintainer-guidelines.txt to RST
doc: Port health-api.txt to RST

 Makefile.am                                   |  30 +-
 doc/assigned-numbers.rst                      |  29 ++
 doc/assigned-numbers.txt                      |  26 --
 doc/coding-style.rst                          | 349 ++++++++++++++++++
 doc/coding-style.txt                          | 279 --------------
 doc/health-api.txt                            | 152 --------
 ...idelines.txt => maintainer-guidelines.rst} |  61 +--
 doc/org.bluez.HealthChannel.rst               |  72 ++++
 doc/org.bluez.HealthDevice.rst                |  94 +++++
 doc/org.bluez.HealthManager.rst               |  68 ++++
 doc/org.bluez.SimAccess.rst                   |  40 ++
 doc/org.bluez.Thermometer.rst                 |  51 +++
 doc/org.bluez.ThermometerManager.rst          |  64 ++++
 doc/org.bluez.ThermometerWatcher.rst          |  79 ++++
 doc/sap-api.txt                               |  20 -
 doc/{security-bugs.txt => security-bugs.rst}  |   1 +
 doc/thermometer-api.txt                       | 134 -------
 17 files changed, 908 insertions(+), 641 deletions(-)
 create mode 100644 doc/assigned-numbers.rst
 delete mode 100644 doc/assigned-numbers.txt
 create mode 100644 doc/coding-style.rst
 delete mode 100644 doc/coding-style.txt
 delete mode 100644 doc/health-api.txt
 rename doc/{maintainer-guidelines.txt => maintainer-guidelines.rst} (65%)
 create mode 100644 doc/org.bluez.HealthChannel.rst
 create mode 100644 doc/org.bluez.HealthDevice.rst
 create mode 100644 doc/org.bluez.HealthManager.rst
 create mode 100644 doc/org.bluez.SimAccess.rst
 create mode 100644 doc/org.bluez.Thermometer.rst
 create mode 100644 doc/org.bluez.ThermometerManager.rst
 create mode 100644 doc/org.bluez.ThermometerWatcher.rst
 delete mode 100644 doc/sap-api.txt
 rename doc/{security-bugs.txt => security-bugs.rst} (99%)
 delete mode 100644 doc/thermometer-api.txt
Signature · 1 line
2.52.0
#1 lore raw

PATCH v2 1/7 doc: Port assigned-numbers.txt to RST

---
 Makefile.am              |  2 +-
 doc/assigned-numbers.rst | 29 +++++++++++++++++++++++++++++
 doc/assigned-numbers.txt | 26 --------------------------
 3 files changed, 30 insertions(+), 27 deletions(-)
 create mode 100644 doc/assigned-numbers.rst
 delete mode 100644 doc/assigned-numbers.txt
Makefile.am +1 -1
index 3adfa6cd51c3..acd28732aa2d 100644
@@ -473,7 +473,7 @@ endif
 
 EXTRA_DIST += $(test_scripts)
 
-EXTRA_DIST += doc/assigned-numbers.txt doc/supported-features.txt \
+EXTRA_DIST += doc/assigned-numbers.rst doc/supported-features.txt \
 				doc/test-coverage.txt \
 				doc/test-runner.rst \
 				doc/settings-storage.txt
doc/assigned-numbers.rst new file +29 -0
new file mode 100644
index 000000000000..e3fcb65b83df
@@ -0,0 +1,29 @@
+===============
+RFCOMM Channels
+===============
+
+Since there are a limited amount of possible RFCOMM channels (1-31)
+they've been pre-allocated for currently known profiles in order to
+avoid conflicts.
+
+.. csv-table::
+	:header: "Profile", "Channel"
+	:widths: auto
+
+	DUN, 1
+	SPP, 3
+	HSP HS, 6
+	HFP HF, 7
+	OPP, 9
+	FTP, 10
+	BIP, 11
+	HSP AG, 12
+	HFP AG, 13
+	SYNCH (IrMC), 14
+	PBAP, 15
+	MAP MAS, 16
+	MAP MNS, 17
+	SyncEvolution, 19
+	PC/Ovi Suite, 24
+	SyncML Client, 25
+	SyncML Server, 26
doc/assigned-numbers.txt deleted +0 -26
deleted file mode 100644
index cf481c15eb88..000000000000
@@ -1,26 +0,0 @@
-RFCOMM Channels
-===============
-
-Since there are a limited amount of possible RFCOMM channels (1-31)
-they've been pre-allocated for currently known profiles in order to
-avoid conflicts.
-
-Profile		Channel
------------------------
-DUN		1
-SPP		3
-HSP HS		6
-HFP HF		7
-OPP		9
-FTP		10
-BIP		11
-HSP AG		12
-HFP AG		13
-SYNCH (IrMC)	14
-PBAP		15
-MAP MAS		16
-MAP MNS		17
-SyncEvolution	19
-PC/Ovi Suite	24
-SyncML Client	25
-SyncML Server	26
Signature · 1 line
2.52.0
#2 lore raw

This is automated email and please do not reply to this email!

Dear submitter,

Thank you for submitting the patches to the linux bluetooth mailing list. This is a CI test results with your patch series:
PW Link:https://patchwork.kernel.org/project/bluetooth/list/?series=1044790

---Test result---

Test Summary:

CheckPatch                    PENDING   0.43 seconds
GitLint                       PENDING   0.30 seconds
BuildEll                      PASS      19.81 seconds
BluezMake                     PASS      624.90 seconds
MakeCheck                     PASS      18.15 seconds
MakeDistcheck                 PASS      240.52 seconds
CheckValgrind                 PASS      291.00 seconds
CheckSmatch                   PASS      348.67 seconds
bluezmakeextell               PASS      180.97 seconds
IncrementalBuild              PENDING   0.34 seconds
ScanBuild                     PASS      1009.27 seconds

Details
##############################
Test: CheckPatch - PENDING
Desc: Run checkpatch.pl script
Output:

##############################
Test: GitLint - PENDING
Desc: Run gitlint
Output:

##############################
Test: IncrementalBuild - PENDING
Desc: Incremental build with the patches in the series Output:

---
Regards,
Linux Bluetooth

#3 lore raw

PATCH v2 2/7 doc: Port thermometer-api.txt to RST

In reply to Bastien Nocera
---
 Makefile.am                          |  10 ++
 doc/org.bluez.Thermometer.rst        |  51 ++++++++++
 doc/org.bluez.ThermometerManager.rst |  64 +++++++++++++
 doc/org.bluez.ThermometerWatcher.rst |  79 ++++++++++++++++
 doc/thermometer-api.txt              | 134 ---------------------------
 5 files changed, 204 insertions(+), 134 deletions(-)
 create mode 100644 doc/org.bluez.Thermometer.rst
 create mode 100644 doc/org.bluez.ThermometerManager.rst
 create mode 100644 doc/org.bluez.ThermometerWatcher.rst
 delete mode 100644 doc/thermometer-api.txt
Makefile.am +10 -0
index acd28732aa2d..d80c1250a417 100644
@@ -399,6 +399,9 @@ man_MANS += doc/org.bluez.obex.Client.5 doc/org.bluez.obex.Session.5 \
 		doc/org.bluez.obex.AgentManager.5 doc/org.bluez.obex.Agent.5 \
 		doc/org.bluez.obex.Image.5
 man_MANS += doc/org.bluez.Telephony.5 doc/org.bluez.Call.5
+man_MANS += doc/org.bluez.ThermometerManager.5 \
+		doc/org.bluez.Thermometer.5 \
+		doc/org.bluez.ThermometerWatcher.5
 endif
 manual_pages += src/bluetoothd.8
 manual_pages += doc/hci.7 doc/mgmt.7 doc/l2cap.7 doc/rfcomm.7 doc/sco.7 \
@@ -436,6 +439,9 @@ manual_pages += doc/org.bluez.obex.Client.5 doc/org.bluez.obex.Session.5 \
 		doc/org.bluez.obex.AgentManager.5 doc/org.bluez.obex.Agent.5 \
 		doc/org.bluez.obex.Image.5
 manual_pages += doc/org.bluez.Telephony.5 doc/org.bluez.Call.5
+manual_pages += doc/org.bluez.ThermometerManager.5 \
+		doc/org.bluez.Thermometer.5 \
+		doc/org.bluez.ThermometerWatcher.5
 
 EXTRA_DIST += src/genbuiltin src/bluetooth.conf \
 			src/main.conf profiles/network/network.conf \
@@ -522,6 +528,10 @@ EXTRA_DIST += doc/org.bluez.obex.Client.rst doc/org.bluez.obex.Session.rst \
 
 EXTRA_DIST += doc/org.bluez.Telephony.rst doc/org.bluez.Call.rst
 
+EXTRA_DIST += doc/org.bluez.ThermometerManager.rst \
+	      doc/org.bluez.Thermometer.rst \
+	      doc/org.bluez.ThermometerWatcher.rst
+
 EXTRA_DIST += doc/pics-opp.txt doc/pixit-opp.txt \
 		doc/pts-opp.txt
 
doc/org.bluez.Thermometer.rst new file +51 -0

51 lines not on this page · raw message

doc/org.bluez.ThermometerManager.rst new file +64 -0

64 lines not on this page · raw message

doc/org.bluez.ThermometerWatcher.rst new file +79 -0

79 lines not on this page · raw message

doc/thermometer-api.txt deleted +0 -134

134 lines not on this page · raw message

Signature · 1 line
2.52.0
#4 lore raw

PATCH v2 3/7 doc: Port security-bugs.txt to RST

In reply to Bastien Nocera
---
 doc/{security-bugs.txt => security-bugs.rst} | 1 +
 1 file changed, 1 insertion(+)
 rename doc/{security-bugs.txt => security-bugs.rst} (99%)
doc/security-bugs.rst renamed from doc/security-bugs.txt +1 -0
similarity index 99%
rename from doc/security-bugs.txt
rename to doc/security-bugs.rst
index bd4b0d68f309..0dcacfbd9eac 100644
@@ -1,3 +1,4 @@
+=============
 Security bugs
 =============
 
Signature · 1 line
2.52.0
#5 lore raw

PATCH v2 4/7 doc: Port coding-style.txt to RST

In reply to Bastien Nocera
---
 doc/coding-style.rst | 349 +++++++++++++++++++++++++++++++++++++++++++
 doc/coding-style.txt | 279 ----------------------------------
 2 files changed, 349 insertions(+), 279 deletions(-)
 create mode 100644 doc/coding-style.rst
 delete mode 100644 doc/coding-style.txt
doc/coding-style.rst new file +349 -0
new file mode 100644
index 000000000000..91250e867f09
@@ -0,0 +1,349 @@
+==================
+BlueZ coding style
+==================
+
+Every project has its coding style, and BlueZ is not an exception. This
+document describes the preferred coding style for BlueZ code, in order to keep
+some level of consistency among developers so that code can be easily
+understood and maintained.
+
+First of all, BlueZ coding style must follow every rule for Linux kernel
+(https://www.kernel.org/doc/Documentation/process/coding-style.rst). There also
+exists a tool named checkpatch.pl to help you check the compliance with it.
+Just type ``checkpatch.pl --no-tree patch_name`` to check your patch. In theory,
+you need to clean up all the warnings and errors except this one: ``ERROR:
+Missing Signed-off-by: line(s)``. BlueZ does not used ``Signed-off-by`` lines, so
+including them is actually an error. In certain circumstances one can ignore
+the 80 character per line limit. This is generally only allowed if the
+alternative would make the code even less readable.
+
+Besides the kernel coding style above, BlueZ has special flavors for its own.
+Some of them are mandatory (marked as ``M``), while some others are optional
+(marked as ``O``), but generally preferred.
+
+M1: Blank line before and after an if/while/do/for statement
+------------------------------------------------------------
+
+There should be a blank line before ``if`` statement unless the ``if`` is nested and
+not preceded by an expression or variable declaration.
+
+Example:
+1)
+
+.. code-block:: C
+
+        a = 1;
+        if (b) {  // wrong
+
+2)
+
+.. code-block:: C
+
+        a = 1
+
+        if (b) {
+        }
+        a = 2;	// wrong
+
+3)
+
+.. code-block:: C
+
+        if (a) {
+	        if (b)  // correct
+
+4)
+
+.. code-block:: C
+
+        b = 2;
+
+        if (a) {	// correct
+
+        }
+
+        b = 3;
+
+The only exception to this rule applies when a variable is being checked for
+errors as such:
+
+.. code-block:: C
+
+        err = stat(filename, &st);
+        if (err || !S_ISDIR(st.st_mode))
+	        return;
+
+M2: Multiple line comment
+-------------------------
+
+If your comment has more than one line, please start it from the second line.
+
+Example:
+
+.. code-block:: C
+
+        /*
+         * first line comment	// correct
+         * ...
+         * last line comment
+         */
+
+M3: Space before and after operator
+-----------------------------------
+
+There should be a space before and after each operator.
+
+Example:
+
+.. code-block:: C
+
+        a + b;  // correct
+
+
+M4: Wrap long lines
+-------------------
+
+If your condition in ``if``, ``while``, ``for`` statement or a function declaration is too
+long to fit in one line, the new line needs to be indented not aligned with the
+body.
+
+Example:
+1)
+
+.. code-block:: C
+
+        if ((adapter->supported_settings & MGMT_SETTING_SSP) &&
+        	!(adapter->current_settings & MGMT_SETTING_SSP)) // wrong
+
+2)
+
+.. code-block:: C
+
+        if ((adapter->supported_settings & MGMT_SETTING_SSP) &&
+	        			!(adapter->current_settings & MGMT_SETTING_SSP))
+
+3)
+
+.. code-block:: C
+
+        void btd_adapter_register_pin_cb(struct btd_adapter *adapter,
+	        			 btd_adapter_pin_cb_t cb) // wrong
+
+4)
+
+.. code-block:: C
+
+        void btd_adapter_register_pin_cb(struct btd_adapter *adapter,
+	        						btd_adapter_pin_cb_t cb)
+
+The referred style for line wrapping is to indent as far as possible to the
+right without hitting the 80 columns limit.
+
+M5: Space when doing type casting
+---------------------------------
+
+There should be a space between new type and variable.
+
+Example:
+1)
+
+.. code-block:: C
+
+        a = (int *)b;  // wrong
+
+2)
+
+.. code-block:: C
+
+        a = (int *) b;  // correct
+
+
+M6: Don't initialize variable unnecessarily
+-------------------------------------------
+
+When declaring a variable, try not to initialize it unless necessary.
+
+Example:
+
+.. code-block:: C
+
+        int i = 1;  // wrong
+
+        for (i = 0; i < 3; i++) {
+        }
+
+M7: Follow the order of include header elements
+-----------------------------------------------
+
+When writing an include header the various elements should be in the following
+order:
+
+* ``#include``'s
+* forward declarations
+* ``#define``'s
+* ``enum``'s
+* ``typedef``'s
+* function declarations and inline function definitions
+
+M8: Internal headers must not use include guards
+------------------------------------------------
+
+Any time when creating a new header file with non-public API, that header
+must not contain include guards.
+
+M9: Naming of enums
+-------------------
+
+Enums must have a descriptive name.  The enum type should be small caps and
+it should not be ``typedef``'ed.  Enum contents should be in CAPITAL letters and
+prefixed by the ``enum`` type name.
+
+Example:
+
+.. code-block:: C
+
+        enum animal_type {
+        	ANIMAL_TYPE_FOUR_LEGS,
+        	ANIMAL_TYPE_EIGHT_LEGS,
+        	ANIMAL_TYPE_TWO_LEGS,
+        };
+
+If the enum contents have values (e.g. from specification) the formatting
+should be as follows:
+
+.. code-block:: C
+
+        enum animal_type {
+        	ANIMAL_TYPE_FOUR_LEGS =		4,
+        	ANIMAL_TYPE_EIGHT_LEGS =	8,
+        	ANIMAL_TYPE_TWO_LEGS =		2,
+        };
+
+M10: Enum as switch variable
+----------------------------
+
+If the variable of a ``switch`` is an enum, you must include all values in
+switch body even if providing ``default``. This is enforced by compiler option
+enabling extra warning in such case. The reason for this is to ensure that if
+later on the enum is modified and one forget to change the ``switch`` accordingly, the
+compiler will complain the new added type hasn't been handled.
+
+Example:
+
+.. code-block:: C
+
+        enum animal_type {
+        	ANIMAL_TYPE_FOUR_LEGS =		4,
+        	ANIMAL_TYPE_EIGHT_LEGS =	8,
+        	ANIMAL_TYPE_TWO_LEGS =		2,
+        };
+
+        enum animal_type t;
+
+        switch (t) { // OK
+        case ANIMAL_TYPE_FOUR_LEGS:
+        	...
+        	break;
+        case ANIMAL_TYPE_EIGHT_LEGS:
+        	...
+        	break;
+        case ANIMAL_TYPE_TWO_LEGS:
+        	...
+        	break;
+        default:
+        	break;
+        }
+
+        switch (t) { // Wrong
+        case ANIMAL_TYPE_FOUR_LEGS:
+        	...
+        	break;
+        case ANIMAL_TYPE_TWO_LEGS:
+        	...
+        	break;
+        default:
+        	break;
+        }
+
+However if the enum comes from an external header file outside BlueZ, such as
+Android headers, we cannot make any assumption of how the enum is defined and
+this rule might not apply.
+
+M11: Always use parenthesis with sizeof
+---------------------------------------
+
+The expression argument to the ``sizeof`` operator should always be in
+parenthesis, too.
+
+Example:
+1)
+
+.. code-block:: C
+
+        memset(stuff, 0, sizeof(*stuff));
+
+2)
+
+.. code-block:: C
+
+        memset(stuff, 0, sizeof *stuff); // Wrong
+
+M12: Use void if function has no parameters
+-------------------------------------------
+
+A function with no parameters must use ``void`` in the parameter list.
+
+Example:
+1)
+
+.. code-block:: C
+
+        void foo(void)
+        {
+        }
+
+2)
+
+.. code-block:: C
+
+        void foo()	// Wrong
+        {
+        }
+
+O1: Try to avoid complex if body
+--------------------------------
+
+It's better not to have a complicated statement for ``if``. You may judge its
+contrary condition and ``return``, ``break``, ``continue`` or ``goto`` as soon
+as possible.
+
+Example:
+
+1)
+
+.. code-block:: C
+
+        if (device) {  // worse
+        	memset(&eir_data, 0, sizeof(eir_data));
+        	if (eir_len > 0)
+        		eir_parse(&eir_data, ev->eir, eir_len);
+        	...
+        } else {
+        	error("Unable to get device object for %s", addr);
+        	return;
+        }
+
+2)
+
+.. code-block:: C
+
+        if (!device) {
+        	error("Unable to get device object for %s", addr);
+        	return;
+        }
+
+        memset(&eir_data, 0, sizeof(eir_data));
+        if (eir_len > 0)
+        	eir_parse(&eir_data, ev->eir, eir_len);
+        ...
+
doc/coding-style.txt deleted +0 -279

279 lines not on this page · raw message

Signature · 1 line
2.52.0
#6 lore raw

PATCH v2 5/7 doc: Port sap-api.txt to RST

In reply to Bastien Nocera
---
 Makefile.am                 |  8 ++++++--
 doc/org.bluez.SimAccess.rst | 40 +++++++++++++++++++++++++++++++++++++
 doc/sap-api.txt             | 20 -------------------
 3 files changed, 46 insertions(+), 22 deletions(-)
 create mode 100644 doc/org.bluez.SimAccess.rst
 delete mode 100644 doc/sap-api.txt
Makefile.am +6 -2
index d80c1250a417..8396849831f1 100644
@@ -402,6 +402,8 @@ man_MANS += doc/org.bluez.Telephony.5 doc/org.bluez.Call.5
 man_MANS += doc/org.bluez.ThermometerManager.5 \
 		doc/org.bluez.Thermometer.5 \
 		doc/org.bluez.ThermometerWatcher.5
+man_MANS += doc/org.bluez.SimAccess.5
+
 endif
 manual_pages += src/bluetoothd.8
 manual_pages += doc/hci.7 doc/mgmt.7 doc/l2cap.7 doc/rfcomm.7 doc/sco.7 \
@@ -442,6 +444,7 @@ manual_pages += doc/org.bluez.Telephony.5 doc/org.bluez.Call.5
 manual_pages += doc/org.bluez.ThermometerManager.5 \
 		doc/org.bluez.Thermometer.5 \
 		doc/org.bluez.ThermometerWatcher.5
+manual_pages += doc/org.bluez.SimAccess.5
 
 EXTRA_DIST += src/genbuiltin src/bluetooth.conf \
 			src/main.conf profiles/network/network.conf \
@@ -484,8 +487,7 @@ EXTRA_DIST += doc/assigned-numbers.rst doc/supported-features.txt \
 				doc/test-runner.rst \
 				doc/settings-storage.txt
 
-EXTRA_DIST += doc/health-api.txt \
-		doc/sap-api.txt
+EXTRA_DIST += doc/health-api.txt
 
 EXTRA_DIST += doc/hci.rst doc/mgmt.rst doc/l2cap.rst doc/rfcomm.rst \
 	      doc/sco.rst doc/iso.rst
@@ -532,6 +534,8 @@ EXTRA_DIST += doc/org.bluez.ThermometerManager.rst \
 	      doc/org.bluez.Thermometer.rst \
 	      doc/org.bluez.ThermometerWatcher.rst
 
+EXTRA_DIST += doc/org.bluez.SimAccess.rst
+
 EXTRA_DIST += doc/pics-opp.txt doc/pixit-opp.txt \
 		doc/pts-opp.txt
 
doc/org.bluez.SimAccess.rst new file +40 -0
new file mode 100644
index 000000000000..ac86e7eb220c
@@ -0,0 +1,40 @@
+===================
+org.bluez.SimAccess
+===================
+
+----------------------------------------
+BlueZ D-Bus Sim Access API documentation
+----------------------------------------
+
+:Version: BlueZ
+:Date: February 2011
+:Author: Waldemar Rymarkiewicz <[email protected]>
+:Manual section: 5
+:Manual group: Linux System Administration
+
+Interface
+=========
+
+:Service:	org.bluez
+:Interface:	org.bluez.SimAccess1
+:Object path:	[variable prefix]/{hci0,hci1,...}
+
+Methods
+-------
+
+void Disconnect()
+`````````````````
+Disconnects SAP client from the server.
+
+Possible errors:
+
+:org.bluez.Error.Failed:
+
+Properties
+----------
+
+boolean Connected [readonly]
+````````````````````````````
+
+Indicates if SAP client is connected to the server.
+
doc/sap-api.txt deleted +0 -20
deleted file mode 100644
index b28c4e305964..000000000000
@@ -1,20 +0,0 @@
-BlueZ D-Bus Sim Access API description
-**************************************
-
-
-Sim Access Profile hierarchy
-============================
-
-Service		org.bluez
-Interface	org.bluez.SimAccess1
-Object path	[variable prefix]/{hci0,hci1,...}
-
-Methods		void Disconnect()
-
-			Disconnects SAP client from the server.
-
-			Possible errors: org.bluez.Error.Failed
-
-Properties	boolean Connected [readonly]
-
-			Indicates if SAP client is connected to the server.
Signature · 1 line
2.52.0
#7 lore raw

PATCH v2 6/7 doc: Port maintainer-guidelines.txt to RST

In reply to Bastien Nocera
---
 ...idelines.txt => maintainer-guidelines.rst} | 61 +++++++++++--------
 1 file changed, 35 insertions(+), 26 deletions(-)
 rename doc/{maintainer-guidelines.txt => maintainer-guidelines.rst} (65%)
doc/maintainer-guidelines.rst renamed from doc/maintainer-guidelines.txt +35 -26
similarity index 65%
rename from doc/maintainer-guidelines.txt
rename to doc/maintainer-guidelines.rst
index b875f008258b..a6e756b81c51 100644
@@ -1,25 +1,28 @@
+=====================
 Maintainer guidelines
-*********************
+=====================
 
 This document is intended for the maintainers of the BlueZ project. It
 serves as basic guidelines for handling patch review and commit access.
 
 
 Rule 1: Keep the GIT tree clean and linear
-==========================================
+------------------------------------------
 
-The bluetooth.git, bluetooth-next.git and bluez.git trees are not your
+The ``bluetooth.git``, ``bluetooth-next.git`` and ``bluez.git`` trees are not your
 private playground. The history is meant to be clean and linear.
 
-	- NO merges
-	- NO branches
-	- NO tags
+- NO merges
+- NO branches
+- NO tags
 
 If anyone needs testing or work on a feature, clone the tree and do
 it in your own copy. The master trees are off limits.
 
 One advise to avoid any accidental errors in this area to set proper
-options in global ~/.gitconfig or local .git/config files.
+options in global ``~/.gitconfig`` or local ``.git/config`` files.
+
+.. code-block::
 
 	[merge]
 		ff = only
@@ -29,7 +32,7 @@ in doubt ask one of the seasoned maintainers.
 
 
 Rule 2: Enforce clean commit messages
-=====================================
+-------------------------------------
 
 The commit messages are required to be clean and follow style guidelines
 to be consistent.
@@ -45,20 +48,22 @@ job to ensure we get proper firstname lastname <email> authorship.
 
 It is also important that the committer itself uses a valid name and
 email address when committing patches. So ensure that either the
-global ~/.gitconfig or local .git/config provides proper values.
+global ``~/.gitconfig`` or local ``.git/config`` provides proper values.
+
+.. code-block::
 
 	[user]
 		name = Peter Mustermann
 		email = [email protected]
 
-Commit messages for bluez.git shall not contain Signed-off-by
+Commit messages for ``bluez.git`` shall not contain ``Signed-off-by``
 signatures. They are not used in userspace and with that it is the
 maintainers job to ensure they do not get committed to the repository.
 
-For bluetooth.git and bluetooth-next.git The Signed-off-by process is
-used and the signatures are required.
+For ``bluetooth.git`` and ``bluetooth-next.git``, the ``Signed-off-by``
+process is used and the signatures are required.
 
-Tags like Change-Id generated from Gerrit are never acceptable. It is
+Tags like ``Change-Id`` generated from Gerrit are never acceptable. It is
 the maintainers job to ensure that these are not committed into the
 repositories.
 
@@ -67,48 +72,52 @@ reversed. If in doubt ask one of the seasoned maintainers.
 
 
 Rule 3: Enforce correct coding style
-====================================
+------------------------------------
 
 The coding style follows roughly the kernel coding style with any
-exceptions documented in doc/coding-style.txt.
+exceptions documented in :doc:`coding-style <coding-style>`.
 
 To ensure trivial white-space errors don't get committed, have the
-following in your .gitconfig:
+following in your ``.gitconfig``:
+
+.. code-block::
 
 	[apply]
 		whitespace = error
 
 It can also be helpful to use the checkpatch.pl script coming with the
 Linux kernel to do some automated checking. Adding the following to your
-.git/hooks/pre-commit and .git/hooks/pre-applypatch is a simple way to
+``.git/hooks/pre-commit`` and ``.git/hooks/pre-applypatch`` is a simple way to
 do this:
 
+.. code-block::
 	exec git diff --cached | ~/src/linux/scripts/checkpatch.pl -q \
 		--no-tree --no-signoff --show-types \
 		--ignore CAMELCASE,NEW_TYPEDEFS,INITIALISED_STATIC -
 
-The above assumes that a kernel tree resides in ~/src/linux/.
+The above assumes that a kernel tree resides in ``~/src/linux/``.
 
 
 Rule 4: Pay extra attention to adding new files to the tree
-===========================================================
+-----------------------------------------------------------
 
 New files that are added to the tree require several things to be
 verified first:
 
-	- Check that the names are acceptable with other maintainers
-	- Ensure that the file modes are correct
-	- Verify that the license & copyright headers are correct
-	- If the file is supposed to be part of the release tarball,
-	  make sure that it gets picked up by 'make dist' (particularly
-	  important for documentation or other files that are not code)
+- Check that the names are acceptable with other maintainers
+- Ensure that the file modes are correct
+- Verify that the license & copyright headers are correct
+- If the file is supposed to be part of the release tarball,
+  make sure that it gets picked up by 'make dist' (particularly
+  important for documentation or other files that are not code)
 
 
 Rule 5: Keep the mailing list in sync with the commit process
-=============================================================
+-------------------------------------------------------------
 
 When applying patches, be sure to send a response to the mailing list as
 soon as the code has been pushed to the upstream tree. Usually this
 means one email per patch, however patch-sets may only have one response
 covering the entire set. If applying a subset of a patch-set clearly
 state what was applied in your response.
+
Signature · 1 line
2.52.0
#8 lore raw

PATCH v2 7/7 doc: Port health-api.txt to RST

In reply to Bastien Nocera
---
 Makefile.am                     |  12 ++-
 doc/health-api.txt              | 152 --------------------------------
 doc/org.bluez.HealthChannel.rst |  72 +++++++++++++++
 doc/org.bluez.HealthDevice.rst  |  94 ++++++++++++++++++++
 doc/org.bluez.HealthManager.rst |  68 ++++++++++++++
 5 files changed, 244 insertions(+), 154 deletions(-)
 delete mode 100644 doc/health-api.txt
 create mode 100644 doc/org.bluez.HealthChannel.rst
 create mode 100644 doc/org.bluez.HealthDevice.rst
 create mode 100644 doc/org.bluez.HealthManager.rst
Makefile.am +10 -2
index 8396849831f1..938b127cd052 100644
@@ -403,6 +403,9 @@ man_MANS += doc/org.bluez.ThermometerManager.5 \
 		doc/org.bluez.Thermometer.5 \
 		doc/org.bluez.ThermometerWatcher.5
 man_MANS += doc/org.bluez.SimAccess.5
+man_MANS += doc/org.bluez.HealthChannel.5 \
+	    doc/org.bluez.HealthDevice.5 \
+	    doc/org.bluez.HealthManager.5
 
 endif
 manual_pages += src/bluetoothd.8
@@ -445,6 +448,9 @@ manual_pages += doc/org.bluez.ThermometerManager.5 \
 		doc/org.bluez.Thermometer.5 \
 		doc/org.bluez.ThermometerWatcher.5
 manual_pages += doc/org.bluez.SimAccess.5
+manual_pages += doc/org.bluez.HealthChannel.5 \
+		doc/org.bluez.HealthDevice.5 \
+		doc/org.bluez.HealthManager.5
 
 EXTRA_DIST += src/genbuiltin src/bluetooth.conf \
 			src/main.conf profiles/network/network.conf \
@@ -487,8 +493,6 @@ EXTRA_DIST += doc/assigned-numbers.rst doc/supported-features.txt \
 				doc/test-runner.rst \
 				doc/settings-storage.txt
 
-EXTRA_DIST += doc/health-api.txt
-
 EXTRA_DIST += doc/hci.rst doc/mgmt.rst doc/l2cap.rst doc/rfcomm.rst \
 	      doc/sco.rst doc/iso.rst
 
@@ -536,6 +540,10 @@ EXTRA_DIST += doc/org.bluez.ThermometerManager.rst \
 
 EXTRA_DIST += doc/org.bluez.SimAccess.rst
 
+EXTRA_DIST += doc/org.bluez.HealthChannel.rst \
+	      doc/org.bluez.HealthDevice.rst \
+	      doc/org.bluez.HealthManager.rst
+
 EXTRA_DIST += doc/pics-opp.txt doc/pixit-opp.txt \
 		doc/pts-opp.txt
 
doc/health-api.txt deleted +0 -152

152 lines not on this page · raw message

doc/org.bluez.HealthChannel.rst new file +72 -0

72 lines not on this page · raw message

doc/org.bluez.HealthDevice.rst new file +94 -0

94 lines not on this page · raw message

doc/org.bluez.HealthManager.rst new file +68 -0

68 lines not on this page · raw message

Signature · 1 line
2.52.0