Lines Matching +full:release +full:- +full:doxygen
14 particularly important for large-scale code bases that follow a library-based
35 want patches that do large-scale reformatting of existing code. On the other
48 environment restrictions, historical restrictions, or due to third-party source
53 For automation, build-systems and utility scripts Python is preferred and
57 ---------------------
60 code and avoid unnecessary vendor-specific extensions.
72 * GCC: https://gcc.gnu.org/projects/cxx-status.html#cxx17
76 * MSVC: https://learn.microsoft.com/cpp/overview/visual-cpp-language-conformance
83 --------------------
92 <https://github.com/llvm/llvm-project/tree/main/llvm/include/llvm/ADT>`_)
109 <https://llvm.org/docs/ProgrammersManual.html#picking-the-right-data-structure-for-a-task>`_.
112 -----------------------------------------
119 outlined in `PEP 8 <https://peps.python.org/pep-0008/>`_.
123 Use its default rules. For example, avoid specifying ``--line-length`` even
132 the Python format checks in LLVM's pre-commit CI, which also uses darker. When
139 .. code-block:: bash
143 $ darker -r HEAD^ test.py # also format changes from last commit
152 .. code-block:: bash
154 $ darker -r HEAD^ $(git diff --name-only --diff-filter=d HEAD^)
160 ----------------------
178 .. code-block:: c++
180 //===----------------------------------------------------------------------===//
184 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
186 //===----------------------------------------------------------------------===//
192 //===----------------------------------------------------------------------===//
198 The main body is a `Doxygen <http://www.doxygen.nl/>`_ comment (identified by
208 The header file's guard should be the all-caps path that a user of this header
211 ``llvm/include/llvm/Analysis/Utils/Local.h`` would be ``#include``-ed as
218 Classes are a fundamental part of an object-oriented design. As such, a
220 used for and how it works. Every non-trivial class is expected to have a
221 ``doxygen`` comment block.
237 In general, prefer C++-style comments (``//`` for normal comments, ``///`` for
238 ``doxygen`` documentation comments). There are a few cases when it is
239 useful to use C-style (``/* */``) comments however:
245 #. When writing a source file that is used by a tool that only accepts C-style
253 .. code-block:: c++
257 An in-line C-style comment makes the intent obvious:
259 .. code-block:: c++
268 Doxygen Use in Documentation Comments
271 Use the ``\file`` command to turn the standard file header into a file-level
275 member and non-member functions). Avoid restating the information that can
285 Wrap non-inline code examples in ``\code ... \endcode``.
297 .. code-block:: c++
302 A documentation comment that uses all Doxygen features in a preferred way:
304 .. code-block:: c++
325 comments (not necessarily in Doxygen markup) to explain implementation details
335 .. code-block:: c++
339 // example - Does something important.
344 // example - Does something important.
349 .. code-block:: c++
358 /// Builds a B-tree in order to do foo. See paper by...
368 lower-case letter, and finish the last sentence without a period, if it would
374 .. code-block:: none
381 .. code-block:: none
389 including clang, clang-tidy, and so on.
444 order to allow developers to have multiple files side-by-side in
471 When formatting a multi-line lambda, format it like a block of code. If there
472 is only one multi-line lambda in a statement, and there are no expressions
474 indent for a block of code, as if it were an if-block opened by the preceding
477 .. code-block:: c++
479 std::sort(foo.begin(), foo.end(), [&](Foo a, Foo b) -> bool {
491 If there are multiple multi-line lambdas in a statement, or additional
495 .. code-block:: c++
497 dyn_switch(V->stripPointerCasts(),
523 formatting braced initialization lists: act as-if the braces were parentheses
527 .. code-block:: c++
542 ----------------------------
551 .. code-block:: c++
560 .. code-block:: c++
570 you need to rely on non-portable code, put it behind a well-defined and
571 well-documented interface.
578 <https://en.wikipedia.org/wiki/Run-time_type_information>`_, for example,
581 That said, LLVM does make extensive use of a hand-rolled form of RTTI that use
583 This form of RTTI is opt-in and can be
586 Prefer C++-style casts
590 rather than C-style casts. There are two exceptions to this:
593 alternative to ``[[maybe_unused]]``). Prefer C-style casts in this instance.
595 * When casting between integral types (including enums that are not strongly-
596 typed), functional-style casts are permitted as an alternative to
609 <https://yosefk.com/c++fqa/ctors.html#fqa-10.12>`_, making the code more
628 .. code-block:: c++
640 .. code-block:: c++
663 constructors with non-trivial logic or if you care that you're calling some
671 .. code-block:: c++
692 .. code-block:: c++
714 is a copy. Particularly in range-based ``for`` loops, careless copies are
720 .. code-block:: c++
731 for (auto *Ptr : Container) Ptr->change();
733 Beware of non-determinism due to ordering of pointers
739 result in non-deterministic code generation. While the generated code
740 might work correctly, non-determinism can make it harder to reproduce bugs and
748 Beware of non-deterministic sorting order of equal elements
751 ``std::sort`` uses a non-stable sorting algorithm in which the order of equal
753 container having equal elements may result in non-deterministic behavior.
754 To uncover such instances of non-determinism, LLVM has introduced a new
762 The High-Level Issues
763 ---------------------
765 Self-contained Headers
768 Header files should be self-contained (compile on their own) and end in ``.h``.
769 Non-header files that are meant for inclusion should end in ``.inc`` and be
772 All header files should be self-contained. Users and refactoring tools should
777 self-contained. These are typically intended to be included at unusual
780 .inc extension. Use sparingly, and prefer self-contained headers when possible.
802 This doesn't fully enforce all inter-library dependencies, and importantly
806 functions were defined out-of-line. (& for all valid orderings of dependencies
807 - since linking resolution is linear, it's possible that some implicit
831 **must** include all of the header files that you are using --- you can include
862 .. code-block:: c++
881 .. code-block:: c++
910 .. code-block:: c++
913 if (!I->isTerminator() &&
914 I->hasOneUse() && doOtherThing(I)) {
923 *only* does interesting things with non-terminator instructions, and only
934 .. code-block:: c++
938 if (I->isTerminator())
943 if (!I->hasOneUse())
956 .. code-block:: c++
960 Value *LHS = BO->getOperand(0);
961 Value *RHS = BO->getOperand(1);
969 exceeds more than 10-15 lines, it becomes difficult for people to read and
976 .. code-block:: c++
982 Value *LHS = BO->getOperand(0);
983 Value *RHS = BO->getOperand(1);
1000 flow --- like ``return``, ``break``, ``continue``, ``goto``, etc. For example:
1002 .. code-block:: c++
1026 .. code-block:: c++
1046 .. code-block:: c++
1069 .. code-block:: c++
1089 .. code-block:: c++
1093 if (BarList[I]->isFoo()) {
1105 .. code-block:: c++
1110 if (List[I]->isFoo())
1126 being faced with the in-line details of how we check to see if the BarList
1130 The Low-Level Issues
1131 --------------------
1136 Poorly-chosen names can mislead the reader and cause bugs. We cannot stress
1147 nouns and start with an upper-case letter (e.g. ``TextFileReader``).
1154 command-like function should be imperative. The name should be camel case,
1164 should start with an upper-case letter, just like types. Unless the
1172 .. code-block:: c++
1180 style of lower-case words separated by underscores (e.g. ``begin()``,
1187 .. code-block:: c++
1191 Factory<Tire> F; // Avoid: a non-descriptive abbreviation.
1218 .. code-block:: c++
1227 .. code-block:: c++
1229 assert(Ty->isPointerType() && "Can't allocate a non-pointer type!");
1237 assert(isa<PHINode>(Succ->front()) && "Only works on PHId BBs!");
1244 .. code-block:: c++
1254 .. code-block:: c++
1259 and then exit the program. When assertions are disabled (i.e. in release
1279 .. code-block:: c++
1295 .. code-block:: c++
1338 least one out-of-line virtual method in the class. Without this, the compiler
1345 ``-Wswitch`` warns if a switch, without a default label, over an enumeration
1347 covered switch over an enumeration then the ``-Wswitch`` warning won't fire
1349 kinds of defaults, Clang has the warning ``-Wcovered-switch-default`` which is
1353 A knock-on effect of this stylistic requirement is that when building LLVM with
1354 GCC you may get warnings related to "control may reach end of non-void function"
1355 if you return from each case of a covered switch-over-enum because GCC assumes
1360 Use range-based ``for`` loops wherever possible
1363 The introduction of range-based ``for`` loops in C++11 means that explicit
1364 manipulation of iterators is rarely necessary. We use range-based ``for``
1367 .. code-block:: c++
1379 In cases where range-based ``for`` loops can't be used and it is necessary
1380 to write an explicit iterator-based loop, pay close attention to whether
1381 ``end()`` is re-evaluated on each loop iteration. One common mistake is to
1384 .. code-block:: c++
1387 for (auto I = BB->begin(); I != BB->end(); ++I)
1390 The problem with this construct is that it evaluates "``BB->end()``" every time
1395 .. code-block:: c++
1398 for (auto I = BB->begin(), E = BB->end(); I != E; ++I)
1403 "``BB->end()``" may change its value every time through the loop and the second
1410 start of the loop. In this case, the cost is probably minor --- a few extra
1413 expression was actually something like: "``SomeMap[X]->end()``" and map lookups
1435 problematic in this regard --- just ``<iostream>``. However, ``raw_ostream``
1466 .. code-block:: c++
1482 .. code-block:: c++
1493 .. code-block:: c++
1503 -------------------
1505 This section describes preferred low-level formatting guidelines along with
1512 in normal function call expressions and function-like macros. For example:
1514 .. code-block:: c++
1553 .. code-block:: c++
1575 obvious for any reason. For example, the outer-most namespace in a header file
1603 .. code-block:: c++
1624 .. code-block:: c++
1640 contrast, when the function is marked static, you don't need to cross-reference
1643 Don't Use Braces on Simple Single-Statement Bodies of if/else/loop Statements
1655 Similarly, braces should be used when a single-statement body is complex enough
1670 .. code-block:: c++
1724 // Use braces for a `do-while` loop and its enclosing statement.
1725 if (Tok->is(tok::l_brace)) {
1727 Tok = Tok->Next;
1765 <https://www.amazon.com/Effective-Specific-Addison-Wesley-Professional-Computing/dp/0321334876>`_
1769 #. `Large-Scale C++ Software Design
1770 <https://www.amazon.com/Large-Scale-Software-Design-John-Lakos/dp/0201633620>`_