summaryrefslogtreecommitdiff
path: root/Documentation/coding-style.rst
AgeCommit message (Collapse)Author
2024-08-21Documentation: Add documentation-contents.rstDaniel Scally
Add a new .rst file referencing the documentation contents. This file is then included in each documentation page so that we can enhance the Documentation pages on the libcamera website using it. As we do not want the appearance of the libcamera in-tree Documentation to change just yet, disable the new class using the sphinx theme's CSS. To facilitate easier distinguishing between "normal" and documentation pages on the website we want to add a "documentation" class to the content of all such pages. Since this new file will be included on each documentation page it is convenient to add the new directive here - do so. As the website uses different CSS to libcamera, move the contents on docs.rst a little so that the directive at the end of the contents block applies correctly. Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Signed-off-by: Daniel Scally <dan.scally@ideasonboard.com> Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
2024-08-05libcamera: Remove spaces at end of linesLaurent Pinchart
Spaces at end of lines have cropped up in a few places in libcamera. Remove them. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Milan Zamazal <mzamazal@redhat.com> Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
2024-04-17Documentation: coding-style: Clean up header guard styleKieran Bingham
Header guards were replaced by pragma once calls with commits 0a64cf8b7645 ("libcamera: Convert to pragma once") through to 796210ecea82 ("v4l2: Convert to pragma once") Update the coding style to reflect the updated header guard style. Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com> Reviewed-by: Stefan Klug <stefan.klug@ideasonboard.com> Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
2021-11-18Documentation: coding-style: Document the git commit hooksLaurent Pinchart
checkstyle.py is ignored too often. Document how to automate its usage through git commit hooks. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Umang Jain <umang.jain@ideasonboard.com> Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
2021-10-30Documentation: coding-style: Document error handling rulesLaurent Pinchart
Following a conversation on the mailing list about the use of assertions, document the error handling strategy in libcamera. This is an initial set of rules that are expected be extended and detailed in the future. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
2021-08-11clang-format: Regroup sort ordersKieran Bingham
Utilise the clang-format header sort to provide a regex based pattern match for our header inclusion coding style. The rules are updated to match as closely as possible the existing practices and the documentation is updated accordingly. Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Jean-Michel Hautbois <jeanmichel.hautbois@ideasonboard.com> Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
2021-08-09libcamera: Rename 'method' to 'function'Laurent Pinchart
Usage of 'method' to refer to member functions comes from Java. The C++ standard uses the term 'function' only. Replace 'method' with 'function' or 'member function' through the whole code base and documentation. While at it, fix two typos (s/backeng/backend/). The BoundMethod and Object::invokeMethod() are left as-is here, and will be addressed separately. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Paul Elder <paul.elder@ideasonboard.com> Acked-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
2020-12-29utils: checkstyle.py: Drop astyle supportLaurent Pinchart
Formatting code using astyle doesn't lead to results as good as with clang-format, and doesn't receive much test coverage as most developers use clang-format. The code is thus bitrotting. Drop it. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se> Reviewed-by: Paul Elder <paul.elder@ideasonboard.com>
2020-10-07Documentation: coding-style: Document global variable guidelinesPaul Elder
Document the issue related to global variable dependencies and how to avoid them. Signed-off-by: Paul Elder <paul.elder@ideasonboard.com> Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
2020-09-21Documentation: Adjust guidelines regarding math.h headerLaurent Pinchart
While libcamera prefers usage of the C standard library headers (xxx.h) over the C++ version (cxxx), we make an exception for cmath as the overloaded versions of the math functions are convenient. Document this, and adjust checkstyle.py accordingly. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Jacopo Mondi <jacopo@jmondi.org> Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>
2020-08-25meson: Switch to C++17Laurent Pinchart
Due to popular request, move from C++14 to C++17. This will allow dropping some custom constructs (such as a custom utils::clamp), benefiting from new language features, and dropping gcc 5 and 6 from the compilation tests. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com> Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>
2020-06-05docs: coding-style: Change full stop to colonMarvin Schmidt
Signed-off-by: Marvin Schmidt <marvin.schmidt1987@gmail.com> Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com> Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Signed-off-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
2020-05-11Documentation: coding-style: Fix ordered listsLaurent Pinchart
The syntax used for ordered lists is incorrect. Fix it. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>
2020-04-15licenses: Add SPDX headers to RST documentationLaurent Pinchart
The documentation files are licensed under CC-BY-SA-4.0, but this has never been specified explicitly. Add corresponding SPDX headers. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
2020-01-14meson.build: Switch to C++14Laurent Pinchart
C++14 is a minor release that doesn't introduce major new concepts or paradigms compared to C++11, but brings two useful changes for us: - std::make_unique allows dropping our custom implementation in utils. - Functions returning constexpr are not assumed to be const anymore, which is needed to create a standard-conformant span implementation. All the g++ and clang++ versions we support and test (g++-5 onwards and clang++6 onwards) support C++14. However, due to a defect in the original C++14 specification, solved in N4387 ([1]), compilation would fail on g++-5 due to the use of std::map::emplace() with a non-copyable value type. It turns out we can easily fix it by switching to the explicit piecewise emplace() overload. There is thus really nothing holding back the switch. Let's do it, and update the coding style accordingly. [1] http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2015/n4387 Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com> Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>
2019-10-23Documentation: Move coding style under contributingLaurent Pinchart
The coding style isn't so important that it has to be displayed on the top contents bar. Move it to the contributing section. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
2019-10-23Documentation: coding-style: Document order of includesLaurent Pinchart
We follow the Google C++ Style Guide rule on include ordering with a few tweaks. Document our rule explicitly. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com> Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>
2019-10-23Documentation: coding-style: Document usage of C compatibility headersLaurent Pinchart
The C++ standard defines a set of C++ standard library headers, and for some of them, defines C compatibility headers. The former have a name of the form <cxxx> while the later are named <xxx.h>. The C++ headers declare names in the std namespace, and may declare the same names in the global namespace. The C compatibility headers declare names in the global namespace, and may declare the same names in the std namespace. We want to standardise on one set of headers through libcamera, and don't want to rely on optional behaviour. We can thus either use the C++ headers with an explicit std:: namespace qualifier through the code, or the C headers without the qualifier. Both set of headers are defined by the C++ standard, and are thus valid choices. After weighing pros and cons, we have decided to use the C compatibility headers, as nobody wanted to write std::uint32_t. Document this decision. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com> Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>
2019-04-19libcamera: Document documentation style and update the code accordinglyLaurent Pinchart
The documentation style for the Doxygen comment blocks is inconsistent in the library. Document the expectations and update all existing comment blocks to match. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Acked-by: Jacopo Mondi <jacopo@jmondi.org>
2019-02-14Documentation: coding-style: Discourage move on shared_ptr<>Jacopo Mondi
Using std::move() on return statement of a method or on the its returned value prevents the compiler from implementing copy-elision. Discourage that in the coding style document. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
2019-01-22utils: checkstyle: Add support for clang-formatLaurent Pinchart
clang-format produces better results than astyle as it can better match the libcamera coding style. Default to clang-format over astyle, fall back to astyle if clang-format isn't found, and add a --formatter command line option to select a formatter manually. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Kieran Bingham <kieran.bingham@ideasonboard.com> Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>
2019-01-21Documentation: coding_style: Add object ownership rulesLaurent Pinchart
Object ownership is a complex topic that can lead to many issues, from memory leak to crashes. Document the rules that libcamera enforces to make object ownership tracking explicit. This is a first version of the rules and is expected to be expanded as the library is developed. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se> Reviewed-by: Jacopo Mondi <jacopo@jmondi.org>
2019-01-21Documentation: coding_style: Add move semantics to C++11 featuresLaurent Pinchart
Add the move semantics (move constructor and move assignment) to the allowed C++11 features, as we extensively use them for the unique and shared pointers. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Acked-by: Jacopo Mondi <jacopo@jmondi.org>
2019-01-16Documentation: coding_style: Allow C++11 variadic templatesLaurent Pinchart
We make use of the C++11 variadic templates feature in the signal&slot implementation, mark it as allowed in the coding style documentation. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Acked-by: Jacopo Mondi <jacopo@jmondi.org>
2018-12-14Documentation: Document the style check scriptJacopo Mondi
Add a section to the coding style documentation to explain usage of the checkstyle.py script. Signed-off-by: Jacopo Mondi <jacopo@jmondi.org> Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
2018-12-14Documentation: coding-style: Fix list indentationLaurent Pinchart
The various lists in the document are not quoted blocks. Don't indent them. Signed-off-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Acked-by: Jacopo Mondi <jacopo@jmondi.org> Acked-by: Kieran Bingham <kieran.bingham@ideasonboard.com>
2018-12-13Documentation: Add coding style documentJacopo Mondi
Add document to summarize the coding style adopted by libcamera. Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com> Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se> Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>