Skip to contentSkip to conversation

Improve LIRC documentation

PATCH In review Mauro Carvalho Chehab 2 participants 4 messages Nov 26, 2020

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

cover Improve LIRC documentation

Hi Sean,

Those two patches improve LIRC uAPI docs by adding the structs documented at lirc.h to the output of Documentation/output/userspace-api/media/rc/lirc-dev-intro.html

Please review.

Mauro Carvalho Chehab (2):
media: docs: uAPI: rc: dual-license the docs with GPL v2
media: rc: improve LIRC documentation

 Documentation/userspace-api/media/rc/keytable.c.rst |  2 +-
 .../userspace-api/media/rc/lirc-dev-intro.rst       | 13 ++++++++++---
 Documentation/userspace-api/media/rc/lirc-dev.rst   |  2 +-
 Documentation/userspace-api/media/rc/lirc-func.rst  |  2 +-
 .../userspace-api/media/rc/lirc-get-features.rst    |  2 +-
 .../userspace-api/media/rc/lirc-get-rec-mode.rst    |  2 +-
 .../media/rc/lirc-get-rec-resolution.rst            |  2 +-
 .../userspace-api/media/rc/lirc-get-send-mode.rst   |  2 +-
 .../userspace-api/media/rc/lirc-get-timeout.rst     |  2 +-
 .../userspace-api/media/rc/lirc-header.rst          |  2 +-
 Documentation/userspace-api/media/rc/lirc-read.rst  |  2 +-
 .../media/rc/lirc-set-measure-carrier-mode.rst      |  2 +-
 .../media/rc/lirc-set-rec-carrier-range.rst         |  2 +-
 .../userspace-api/media/rc/lirc-set-rec-carrier.rst |  2 +-
 .../media/rc/lirc-set-rec-timeout-reports.rst       |  2 +-
 .../userspace-api/media/rc/lirc-set-rec-timeout.rst |  2 +-
 .../media/rc/lirc-set-send-carrier.rst              |  2 +-
 .../media/rc/lirc-set-send-duty-cycle.rst           |  2 +-
 .../media/rc/lirc-set-transmitter-mask.rst          |  2 +-
 .../media/rc/lirc-set-wideband-receiver.rst         |  2 +-
 Documentation/userspace-api/media/rc/lirc-write.rst |  2 +-
 Documentation/userspace-api/media/rc/rc-intro.rst   |  2 +-
 Documentation/userspace-api/media/rc/rc-protos.rst  |  2 +-
 .../userspace-api/media/rc/rc-sysfs-nodes.rst       |  2 +-
 .../userspace-api/media/rc/rc-table-change.rst      |  2 +-
 Documentation/userspace-api/media/rc/rc-tables.rst  |  2 +-
 .../userspace-api/media/rc/remote_controllers.rst   |  2 +-
 include/uapi/linux/lirc.h                           |  2 +-
 28 files changed, 37 insertions(+), 30 deletions(-)
Signature · 1 line
2.28.0
#1 lore raw

PATCH 1/2 media: docs: uAPI: rc: dual-license the docs with GPL v2

Make the license for those documents also compatible with GPLv2.

---
 Documentation/userspace-api/media/rc/keytable.c.rst             | 2 +-
 Documentation/userspace-api/media/rc/lirc-dev-intro.rst         | 2 +-
 Documentation/userspace-api/media/rc/lirc-dev.rst               | 2 +-
 Documentation/userspace-api/media/rc/lirc-func.rst              | 2 +-
 Documentation/userspace-api/media/rc/lirc-get-features.rst      | 2 +-
 Documentation/userspace-api/media/rc/lirc-get-rec-mode.rst      | 2 +-
 .../userspace-api/media/rc/lirc-get-rec-resolution.rst          | 2 +-
 Documentation/userspace-api/media/rc/lirc-get-send-mode.rst     | 2 +-
 Documentation/userspace-api/media/rc/lirc-get-timeout.rst       | 2 +-
 Documentation/userspace-api/media/rc/lirc-header.rst            | 2 +-
 Documentation/userspace-api/media/rc/lirc-read.rst              | 2 +-
 .../userspace-api/media/rc/lirc-set-measure-carrier-mode.rst    | 2 +-
 .../userspace-api/media/rc/lirc-set-rec-carrier-range.rst       | 2 +-
 Documentation/userspace-api/media/rc/lirc-set-rec-carrier.rst   | 2 +-
 .../userspace-api/media/rc/lirc-set-rec-timeout-reports.rst     | 2 +-
 Documentation/userspace-api/media/rc/lirc-set-rec-timeout.rst   | 2 +-
 Documentation/userspace-api/media/rc/lirc-set-send-carrier.rst  | 2 +-
 .../userspace-api/media/rc/lirc-set-send-duty-cycle.rst         | 2 +-
 .../userspace-api/media/rc/lirc-set-transmitter-mask.rst        | 2 +-
 .../userspace-api/media/rc/lirc-set-wideband-receiver.rst       | 2 +-
 Documentation/userspace-api/media/rc/lirc-write.rst             | 2 +-
 Documentation/userspace-api/media/rc/rc-intro.rst               | 2 +-
 Documentation/userspace-api/media/rc/rc-protos.rst              | 2 +-
 Documentation/userspace-api/media/rc/rc-sysfs-nodes.rst         | 2 +-
 Documentation/userspace-api/media/rc/rc-table-change.rst        | 2 +-
 Documentation/userspace-api/media/rc/rc-tables.rst              | 2 +-
 Documentation/userspace-api/media/rc/remote_controllers.rst     | 2 +-
 27 files changed, 27 insertions(+), 27 deletions(-)
Documentation/userspace-api/media/rc/keytable.c.rst +1 -1
index 0b50cfaf2d86..243e02d2611f 100644
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
 
 file: uapi/v4l/keytable.c
 =========================
Documentation/userspace-api/media/rc/lirc-dev-intro.rst +1 -1
index 167b354bf051..266b646d584e 100644
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
 
 .. _lirc_dev_intro:
 
Documentation/userspace-api/media/rc/lirc-dev.rst +1 -1
index 5510dc02a822..978f86d30fae 100644
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
 
 .. _lirc_dev:
 
Documentation/userspace-api/media/rc/lirc-func.rst +1 -1
index 420a3dbf0d6b..793f295d3ac9 100644
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
 
 .. _lirc_func:
 
Documentation/userspace-api/media/rc/lirc-get-features.rst +1 -1
index 66a243dbd437..4bf25860f932 100644
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
 .. c:namespace:: RC
 
 .. _lirc_get_features:
Documentation/userspace-api/media/rc/lirc-get-rec-mode.rst +1 -1
index 188478ed1233..628fe31792b2 100644
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
 .. c:namespace:: RC
 
 .. _lirc_get_rec_mode:
Documentation/userspace-api/media/rc/lirc-get-rec-resolution.rst +1 -1
index e29445c5ce16..4dfa9c23634b 100644
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
 .. c:namespace:: RC
 
 .. _lirc_get_rec_resolution:
Documentation/userspace-api/media/rc/lirc-get-send-mode.rst +1 -1
index 77472fb5608a..637871805be6 100644
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
 .. c:namespace:: RC
 
 .. _lirc_get_send_mode:
Documentation/userspace-api/media/rc/lirc-get-timeout.rst +1 -1
index f5f3e06d6206..597c3282ae12 100644
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
 .. c:namespace:: RC
 
 .. _lirc_get_min_timeout:
Documentation/userspace-api/media/rc/lirc-header.rst +1 -1
index 8bd0acc9913a..54cb40b8a065 100644
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
 
 .. _lirc_header:
 
Documentation/userspace-api/media/rc/lirc-read.rst +1 -1
index d589560214f4..ce34318698b7 100644
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
 .. c:namespace:: RC
 
 .. _lirc-read:
Documentation/userspace-api/media/rc/lirc-set-measure-carrier-mode.rst +1 -1
index 9bf9811a905a..04ced1aa664b 100644
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
 .. c:namespace:: RC
 
 .. _lirc_set_measure_carrier_mode:
Documentation/userspace-api/media/rc/lirc-set-rec-carrier-range.rst +1 -1
index 530bc223930a..7512dc86b03a 100644
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
 .. c:namespace:: RC
 
 .. _lirc_set_rec_carrier_range:
Documentation/userspace-api/media/rc/lirc-set-rec-carrier.rst +1 -1
index 28c928f1cc14..60e321446ea7 100644
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
 .. c:namespace:: RC
 
 .. _lirc_set_rec_carrier:
Documentation/userspace-api/media/rc/lirc-set-rec-timeout-reports.rst +1 -1
index 83e7155c5796..aebe81012939 100644
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
 .. c:namespace:: RC
 
 .. _lirc_set_rec_timeout_reports:
Documentation/userspace-api/media/rc/lirc-set-rec-timeout.rst +1 -1
index 8f3f9adf54ab..bf9fb2cc61c3 100644
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
 .. c:namespace:: RC
 
 .. _lirc_set_rec_timeout:
Documentation/userspace-api/media/rc/lirc-set-send-carrier.rst +1 -1
index e3810ba58746..a003f9447553 100644
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
 .. c:namespace:: RC
 
 .. _lirc_set_send_carrier:
Documentation/userspace-api/media/rc/lirc-set-send-duty-cycle.rst +1 -1
index 52a072529af9..2979752acbcd 100644
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
 .. c:namespace:: RC
 
 .. _lirc_set_send_duty_cycle:
Documentation/userspace-api/media/rc/lirc-set-transmitter-mask.rst +1 -1
index 68f4cc2e3ae3..38acbcd6e91c 100644
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
 .. c:namespace:: RC
 
 .. _lirc_set_transmitter_mask:
Documentation/userspace-api/media/rc/lirc-set-wideband-receiver.rst +1 -1
index be5321c4a91f..c9d578e291b8 100644
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
 .. c:namespace:: RC
 
 .. _lirc_set_wideband_receiver:
Documentation/userspace-api/media/rc/lirc-write.rst +1 -1
index c1c3230d4fd6..970a8b3fa1ca 100644
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
 .. c:namespace:: RC
 
 .. _lirc-write:
Documentation/userspace-api/media/rc/rc-intro.rst +1 -1
index 1338478e2bd4..2ba62cde2369 100644
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
 
 .. _Remote_controllers_Intro:
 
Documentation/userspace-api/media/rc/rc-protos.rst +1 -1
index 2e290584a210..a2eab3b45647 100644
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
 
 .. _Remote_controllers_Protocols:
 
Documentation/userspace-api/media/rc/rc-sysfs-nodes.rst +1 -1
index 43c442696438..34d6a0a1f4d3 100644
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
 
 .. _remote_controllers_sysfs_nodes:
 
Documentation/userspace-api/media/rc/rc-table-change.rst +1 -1
index 61c77b080ae8..d7de8a56ddfe 100644
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
 
 .. _Remote_controllers_table_change:
 
Documentation/userspace-api/media/rc/rc-tables.rst +1 -1
index 8dc11657fc23..aafbfda1f401 100644
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
 
 .. _Remote_controllers_tables:
 
Documentation/userspace-api/media/rc/remote_controllers.rst +1 -1
index 2d9078accb35..f89291838637 100644
@@ -1,4 +1,4 @@
-.. SPDX-License-Identifier: GFDL-1.1-no-invariants-or-later
+.. SPDX-License-Identifier: GPL-2.0 OR GFDL-1.1-no-invariants-or-later
 .. include:: <isonum.txt>
 
 .. _remote_controllers:
Signature · 1 line
2.28.0
#2 lore raw

PATCH 2/2 media: rc: improve LIRC documentation

In reply to Mauro Carvalho Chehab

Add documentation for enum rc_proto and struct lirc_scancode at the generated docs.

---
 .../userspace-api/media/rc/lirc-dev-intro.rst         | 11 +++++++++--
 include/uapi/linux/lirc.h                             |  2 +-
 2 files changed, 10 insertions(+), 3 deletions(-)
Documentation/userspace-api/media/rc/lirc-dev-intro.rst +9 -2
index 266b646d584e..c88973732282 100644
@@ -57,12 +57,12 @@ on the following table.
 
     This mode is for both sending and receiving IR.
 
-    For transmitting (aka sending), create a ``struct lirc_scancode`` with
+    For transmitting (aka sending), create a struct lirc_scancode with
     the desired scancode set in the ``scancode`` member, :c:type:`rc_proto`
     set to the :ref:`IR protocol <Remote_controllers_Protocols>`, and all other
     members set to 0. Write this struct to the lirc device.
 
-    For receiving, you read ``struct lirc_scancode`` from the LIRC device.
+    For receiving, you read struct lirc_scancode from the LIRC device.
     The ``scancode`` field is set to the received scancode and the
     :ref:`IR protocol <Remote_controllers_Protocols>` is set in
     :c:type:`rc_proto`. If the scancode maps to a valid key code, this is set
@@ -136,6 +136,13 @@ on the following table.
 
     This mode is used only for IR send.
 
+*************************************
+Data types used by LIRC_MODE_SCANCODE
+*************************************
+
+.. kernel-doc:: include/uapi/linux/lirc.h
+    :identifiers: lirc_scancode rc_proto
+
 ********************
 BPF based IR decoder
 ********************
include/uapi/linux/lirc.h +1 -1
index bf0672a6d341..c45a4eaea667 100644
@@ -139,7 +139,7 @@
  */
 #define LIRC_GET_REC_TIMEOUT	       _IOR('i', 0x00000024, __u32)
 
-/*
+/**
  * struct lirc_scancode - decoded scancode with protocol for use with
  *	LIRC_MODE_SCANCODE
  *
Signature · 1 line
2.28.0
maintainer
#3 lore raw
In reply to Mauro Carvalho Chehab
Quoted 6 lines · Mauro Carvalho Chehab

Hi Sean,

Those two patches improve LIRC uAPI docs by adding the structs documented at lirc.h to the output of Documentation/output/userspace-api/media/rc/lirc-dev-intro.html

Please review.

Thanks,

For the series:

Quoted 38 lines

Mauro Carvalho Chehab (2):
media: docs: uAPI: rc: dual-license the docs with GPL v2
media: rc: improve LIRC documentation

 Documentation/userspace-api/media/rc/keytable.c.rst |  2 +-
 .../userspace-api/media/rc/lirc-dev-intro.rst       | 13 ++++++++++---
 Documentation/userspace-api/media/rc/lirc-dev.rst   |  2 +-
 Documentation/userspace-api/media/rc/lirc-func.rst  |  2 +-
 .../userspace-api/media/rc/lirc-get-features.rst    |  2 +-
 .../userspace-api/media/rc/lirc-get-rec-mode.rst    |  2 +-
 .../media/rc/lirc-get-rec-resolution.rst            |  2 +-
 .../userspace-api/media/rc/lirc-get-send-mode.rst   |  2 +-
 .../userspace-api/media/rc/lirc-get-timeout.rst     |  2 +-
 .../userspace-api/media/rc/lirc-header.rst          |  2 +-
 Documentation/userspace-api/media/rc/lirc-read.rst  |  2 +-
 .../media/rc/lirc-set-measure-carrier-mode.rst      |  2 +-
 .../media/rc/lirc-set-rec-carrier-range.rst         |  2 +-
 .../userspace-api/media/rc/lirc-set-rec-carrier.rst |  2 +-
 .../media/rc/lirc-set-rec-timeout-reports.rst       |  2 +-
 .../userspace-api/media/rc/lirc-set-rec-timeout.rst |  2 +-
 .../media/rc/lirc-set-send-carrier.rst              |  2 +-
 .../media/rc/lirc-set-send-duty-cycle.rst           |  2 +-
 .../media/rc/lirc-set-transmitter-mask.rst          |  2 +-
 .../media/rc/lirc-set-wideband-receiver.rst         |  2 +-
 Documentation/userspace-api/media/rc/lirc-write.rst |  2 +-
 Documentation/userspace-api/media/rc/rc-intro.rst   |  2 +-
 Documentation/userspace-api/media/rc/rc-protos.rst  |  2 +-
 .../userspace-api/media/rc/rc-sysfs-nodes.rst       |  2 +-
 .../userspace-api/media/rc/rc-table-change.rst      |  2 +-
 Documentation/userspace-api/media/rc/rc-tables.rst  |  2 +-
 .../userspace-api/media/rc/remote_controllers.rst   |  2 +-
 include/uapi/linux/lirc.h                           |  2 +-
 28 files changed, 37 insertions(+), 30 deletions(-)
Signature · 1 line
2.28.0