[0/5] docs/devel: improve API documentation for QOM

Message ID	20230619171437.357374-1-alex.bennee@linaro.org
Headers	show Delivered-To: patch@linaro.org Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; From: =?utf-8?q?Alex_Benn=C3=A9e?= <alex.bennee@linaro.org> To: qemu-devel@nongnu.org Cc: Eduardo Habkost <eduardo@habkost.net>, =?utf-8?q?Philippe_Mathieu-Daud?= =?utf-8?q?=C3=A9?= <philmd@linaro.org>, =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= <berrange@redhat.com>, Paolo Bonzini <pbonzini@redhat.com>, Markus Armbruster <armbru@redhat.com>, Peter Xu <peterx@redhat.com>, Mark Cave-Ayland <mark.cave-ayland@ilande.co.uk>, Peter Maydell <peter.maydell@linaro.org>, Juan Quintela <quintela@redhat.com>, Richard Henderson <richard.henderson@linaro.org>, Leonardo Bras <leobras@redhat.com>, =?utf-8?q?Alex_Benn=C3=A9e?= <alex.bennee@linaro.org> Subject: [PATCH 0/5] docs/devel: improve API documentation for QOM Date: Mon, 19 Jun 2023 18:14:32 +0100 Message-Id: <20230619171437.357374-1-alex.bennee@linaro.org> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: 8bit Received-SPF: pass client-ip=2a00:1450:4864:20::331; envelope-from=alex.bennee@linaro.org; helo=mail-wm1-x331.google.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action Precedence: list Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: qemu-devel-bounces+patch=linaro.org@nongnu.org
Series	docs/devel: improve API documentation for QOM \| expand [0/5] docs/devel: improve API documentation for QOM [1/5] docs/devel: add some front matter to the devel index [2/5] include/migration: mark vmstate_register() as a legacy function [3/5] include/hw/qdev-core: fixup kerneldoc annotations (!COMPLETE) [4/5] docs/devel: split qom-api reference into new file [5/5] docs/devel: introduce some key concepts for QOM development

Message ID

20230619171437.357374-1-alex.bennee@linaro.org

Headers

Received-SPF: pass (google.com: domain of
 qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as
 permitted sender) client-ip=209.51.188.17;
From: =?utf-8?q?Alex_Benn=C3=A9e?= <alex.bennee@linaro.org>
To: qemu-devel@nongnu.org
Cc: Eduardo Habkost <eduardo@habkost.net>, =?utf-8?q?Philippe_Mathieu-Daud?=
	=?utf-8?q?=C3=A9?= <philmd@linaro.org>,
 =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= <berrange@redhat.com>,
 Paolo Bonzini <pbonzini@redhat.com>, Markus Armbruster <armbru@redhat.com>,
 Peter Xu <peterx@redhat.com>,
 Mark Cave-Ayland <mark.cave-ayland@ilande.co.uk>,
 Peter Maydell <peter.maydell@linaro.org>,
 Juan Quintela <quintela@redhat.com>,
 Richard Henderson <richard.henderson@linaro.org>,
 Leonardo Bras <leobras@redhat.com>,
 =?utf-8?q?Alex_Benn=C3=A9e?= <alex.bennee@linaro.org>
Subject: [PATCH 0/5] docs/devel: improve API documentation for QOM
Date: Mon, 19 Jun 2023 18:14:32 +0100
Message-Id: <20230619171437.357374-1-alex.bennee@linaro.org>
MIME-Version: 1.0
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: 8bit
Received-SPF: pass client-ip=2a00:1450:4864:20::331;
 envelope-from=alex.bennee@linaro.org; helo=mail-wm1-x331.google.com
X-Spam_score_int: -20
X-Spam_score: -2.1
X-Spam_bar: --
X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1,
 DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1,
 RCVD_IN_DNSWL_NONE=-0.0001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001,
 T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no
X-Spam_action: no action
X-BeenThere: qemu-devel@nongnu.org
X-Mailman-Version: 2.1.29
Precedence: list
List-Id: <qemu-devel.nongnu.org>
List-Unsubscribe: <https://lists.nongnu.org/mailman/options/qemu-devel>,
 <mailto:qemu-devel-request@nongnu.org?subject=unsubscribe>
List-Archive: <https://lists.nongnu.org/archive/html/qemu-devel>
List-Post: <mailto:qemu-devel@nongnu.org>
List-Help: <mailto:qemu-devel-request@nongnu.org?subject=help>
List-Subscribe: <https://lists.nongnu.org/mailman/listinfo/qemu-devel>,
 <mailto:qemu-devel-request@nongnu.org?subject=subscribe>
Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org
Sender: qemu-devel-bounces+patch=linaro.org@nongnu.org

Series

docs/devel: improve API documentation for QOM | expand

Message

Alex Bennée June 19, 2023, 5:14 p.m. UTC

Hi,

At the recent QEMU maintainers summit we lamented the fact it was hard
to push forward with our modernising plans as legacy approaches still
get introduced into the code. A lot of knowledge about the "modern"
way of doing things is locked up in senior developers heads. Lets make
a push to improve the developer documentation and ensure best
practice is easy to find.

Some sort of parable about distribution of fishes and knowledge seems
appropriate here.

Alex Bennée (5):
  docs/devel: add some front matter to the devel index
  include/migration: mark vmstate_register() as a legacy function
  include/hw/qdev-core: fixup kerneldoc annotations (!COMPLETE)
  docs/devel: split qom-api reference into new file
  docs/devel: introduce some key concepts for QOM development

 docs/devel/index-api.rst     |   2 +
 docs/devel/index-process.rst |   2 +
 docs/devel/index-tcg.rst     |   2 +
 docs/devel/index.rst         |  24 ++++++-
 docs/devel/qdev-api.rst      |  12 ++++
 docs/devel/qom-api.rst       |   9 +++
 docs/devel/qom.rst           |  50 +++++++++++++-
 docs/devel/tcg.rst           |   2 +
 include/hw/qdev-core.h       | 123 +++++++++++++++++++++++++++++------
 include/migration/vmstate.h  |   9 ++-
 10 files changed, 210 insertions(+), 25 deletions(-)
 create mode 100644 docs/devel/qdev-api.rst
 create mode 100644 docs/devel/qom-api.rst