aboutsummaryrefslogtreecommitdiff
path: root/docs/devel/style.rst
AgeCommit message (Collapse)Author
2023-08-30docs/style: permit inline loop variablesAlex Bennée
I've already wasted enough of my time debugging aliased variables in deeply nested loops. While not scattering variable declarations around is a good aim I think we can make an exception for stuff used inside a loop. Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org> Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Thomas Huth <thuth@redhat.com> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Signed-off-by: Alex Bennée <alex.bennee@linaro.org> Message-Id: <20230829161528.2707696-5-alex.bennee@linaro.org>
2023-07-10docs/devel: Fix coding style in style.rstThomas Huth
As defined earlier in this file, the opening curly brace of functions should be placed on a separate line. So we should do it in the examples here, too. Fixes: 821f296756 ("docs: document use of automatic cleanup functions in glib") Reported-by: Konstantin Kostiuk <kkostiuk@redhat.com> Message-Id: <20230710092638.161625-1-thuth@redhat.com> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Reviewed-by: Konstantin Kostiuk <kkostiuk@redhat.com> Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Thomas Huth <thuth@redhat.com>
2023-04-27docs/style: call out the use of GUARD macrosAlex Bennée
There use makes our code safer so we should mention them. Signed-off-by: Alex Bennée <alex.bennee@linaro.org> Reviewed-by: Philippe Mathieu-Daudé <philmd@linaro.org> Reviewed-by: Juan Quintela <quintela@redhat.com> Reviewed-by: Vladimir Sementsov-Ogievskiy <vsementsov@yandex-team.ru> Message-Id: <20230424092249.58552-19-alex.bennee@linaro.org>
2023-04-27docs/devel: mention the spacing requirement for QOMAlex Bennée
We have a more complete document on QOM but we should at least mention the style requirements in the style guide. Signed-off-by: Alex Bennée <alex.bennee@linaro.org> Reviewed-by: Juan Quintela <quintela@redhat.com> Reviewed-by: Mark Cave-Ayland <mark.cave-ayland@ilande.co.uk> Message-Id: <20230424092249.58552-18-alex.bennee@linaro.org>
2023-04-27docs/devel: make a statement about includesAlex Bennée
While not explicitly disallowing header macro abuse (because that would make us hypocrites) lets at least address some things to think about. Signed-off-by: Alex Bennée <alex.bennee@linaro.org> Reviewed-by: Juan Quintela <quintela@redhat.com> Message-Id: <20230424092249.58552-17-alex.bennee@linaro.org>
2023-01-08docs/devel: Rules on #include in headersMarkus Armbruster
Rules for headers were proposed a long time ago, and generally liked: Message-ID: <87h9g8j57d.fsf@blackfin.pond.sub.org> https://lists.nongnu.org/archive/html/qemu-devel/2016-03/msg03345.html Wortk them into docs/devel/style.rst. Suggested-by: Bernhard Beschow <shentey@gmail.com> Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20221222120813.727830-5-armbru@redhat.com> Reviewed-by: Michael S. Tsirkin <mst@redhat.com> Signed-off-by: Michael S. Tsirkin <mst@redhat.com> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Reviewed-by: Bernhard Beschow <shentey@gmail.com>
2022-04-21doc/style: CLang -> ClangMarc-André Lureau
It's not the way it is usually written (see https://clang.llvm.org/). Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com> Reviewed-by: Damien Hedde <damien.hedde@greensocs.com> Reviewed-by: Philippe Mathieu-Daudé <f4bug@amsat.org> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> Message-Id: <20220420132624.2439741-17-marcandre.lureau@redhat.com>
2022-02-09docs/devel: mention our .editorconfigAlex Bennée
Ideally we should keep all our automatic formatting gubins in here. Signed-off-by: Alex Bennée <alex.bennee@linaro.org> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Tested-by: Philippe Mathieu-Daudé <f4bug@amsat.org> Reviewed-by: Philippe Mathieu-Daudé <f4bug@amsat.org> Message-Id: <20220204204335.1689602-13-alex.bennee@linaro.org>
2022-01-18docs/devel: more documentation on the use of suffixesAlex Bennée
Using _qemu is a little confusing. Let's use _compat for these sorts of things. We should also mention _impl which is another common suffix in the code base. Signed-off-by: Alex Bennée <alex.bennee@linaro.org> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com> Message-Id: <20220105135009.1584676-25-alex.bennee@linaro.org>
2022-01-18docs/devel: update C standard to C11Alex Bennée
Since 8a9d3d5640 (configure: Use -std=gnu11) we have allowed C11 code so lets reflect that in the style guide. Signed-off-by: Alex Bennée <alex.bennee@linaro.org> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com> Message-Id: <20220105135009.1584676-24-alex.bennee@linaro.org>
2021-11-22docs: Fix botched rST conversion of 'submitting-a-patch.rst'Kashyap Chamarthy
I completely botched up the merged[0] rST conversion of this document by accidentally dropping entire hunks (!) of text. :-( I made it very hard for reviewers to spot it, as the omitted text was buried deep in the document. To fix my hatchet job, I reconverted the "SubmitAPatch" wiki[1] page from scratch and replaced the existing rST with it, while making sure I incorporated previous feedback. In summary, in this reconverted edition: - I did a careful (to the extent my eyes allowed) para-by-para comparison of the wiki and the rST to make sure I didn't omit anything accidentally. - I made sure to work in the cosmetic feedback[2] that Thomas Huth pointed out in the merged (and botched) edition: - fix the hyperlinks in "Split up long patches" - replace ".". with "does not end with a dot" (in "Write a meaningful commit message" section) - replace "---" with ``---`` so that it doesn't render as an em-dash (there were two other occurrences; I fixed those too) - Use "QEMU" spelling consistently in prose usage - Add a consistent "refer to git-config" link where appropriate Thanks to Thomas Huth and Alex Bennée for noticing it on IRC. And sorry for my sloppiness. Fixes: 9f73de8df033 ("docs: rSTify the "SubmitAPatch" wiki") [0] https://gitlab.com/qemu-project/qemu/-/commit/9f73de8df033 [1] https://wiki.qemu.org/index.php?title=Contribute/SubmitAPatch&oldid=10387 [2] https://lists.nongnu.org/archive/html/qemu-devel/2021-11/msg03600.html Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com> Message-Id: <20211119193118.949698-2-kchamart@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> [thuth: Some more cosmetical changes, fixed links from external to internal] Signed-off-by: Thomas Huth <thuth@redhat.com>
2021-11-19docs: Spell QEMU all capsPhilippe Mathieu-Daudé
Replace Qemu -> QEMU. Signed-off-by: Philippe Mathieu-Daudé <philmd@redhat.com> Reviewed-by: Darren Kenny <darren.kenny@oracle.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20211118143401.4101497-1-philmd@redhat.com> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2021-03-24docs/devel: expand style section of memory managementAlex Bennée
This aims to provide a bit more guidance for those who take on one of our "clean up memory allocation" bite-sized tasks. Signed-off-by: Alex Bennée <alex.bennee@linaro.org> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Message-Id: <20210323165308.15244-4-alex.bennee@linaro.org>
2021-02-24docs: move CODING_STYLE into the developer documentationAlex Bennée
There is no particular reason to keep this on it's own in the root of the tree. Move it into the rest of the fine developer manual and fixup any links to it. The only tweak I've made is to fix the code-block annotations to mention the language C. Signed-off-by: Alex Bennée <alex.bennee@linaro.org> Reviewed-by: Claudio Fontana <cfontana@suse.de> Message-Id: <20210223095931.16908-1-alex.bennee@linaro.org>