CbC/CbC_llvm: docs/CodingStandards.rst comparison

comparison docs/CodingStandards.rst @ 120:1172e4bd9c6f

update 4.0.0

author	mir3636
date	Fri, 25 Nov 2016 19:14:25 +0900
parents	afa8332a0e37
children	803732b1fca8

comparison

equal deleted inserted replaced

-:34baf5011add
+:1172e4bd9c6f
 Supported C++11 Language and Library Features
 ---------------------------------------------
 While LLVM, Clang, and LLD use C++11, not all features are available in all of
 the toolchains which we support. The set of features supported for use in LLVM
-is the intersection of those supported in MSVC 2013, GCC 4.7, and Clang 3.1.
+is the intersection of those supported in the minimum requirements described
+in the :doc:`GettingStarted` page, section `Software`.
 The ultimate definition of this set is what build bots with those respective
 toolchains accept. Don't argue with the build bots. However, we have some
 guidance below to help you know what to expect.
 Each toolchain provides a good reference for what it accepts:
 * ``override`` and ``final``: N2928_, N3206_, N3272_
 * Atomic operations and the C++11 memory model: N2429_
 * Variadic templates: N2242_
 * Explicit conversion operators: N2437_
 * Defaulted and deleted functions: N2346_
-* But not defaulted move constructors or move assignment operators, MSVC 2013
-cannot synthesize them.
 * Initializer lists: N2627_
 * Delegating constructors: N1986_
 * Default member initializers (non-static data member initializers): N2756_
 * Only use these for scalar members that would otherwise be left
 uninitialized. Non-scalar members generally have appropriate default
-constructors, and MSVC 2013 has problems when braced initializer lists are
+constructors.
-involved.
 .. _N2118: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2118.html
 .. _N2439: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2439.htm
 .. _N1720: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2004/n1720.html
 .. _N1984: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1984.pdf
 the Linux build bots to find out if your usage triggered a bug. For example, if
 you hit a type trait which doesn't work we can then add support to LLVM's
 traits header to emulate it.
 .. _the libstdc++ manual:
-http://gcc.gnu.org/onlinedocs/gcc-4.7.3/libstdc++/manual/manual/status.html#status.iso.2011
+http://gcc.gnu.org/onlinedocs/gcc-4.8.0/libstdc++/manual/manual/status.html#status.iso.2011
 Other Languages
 ---------------
 Any code written in the Go programming language is not subject to the
 file is released under.  This makes it perfectly clear what terms the source
 code can be distributed under and should not be modified in any way.
 The main body is a ``doxygen`` comment (identified by the ``///`` comment
 marker instead of the usual ``//``) describing the purpose of the file.  The
-first sentence or a passage beginning with ``\brief`` is used as an abstract.
+first sentence (or a passage beginning with ``\brief``) is used as an abstract.
 Any additional information should be separated by a blank line.  If an
 algorithm is being implemented or something tricky is going on, a reference
 to the paper where it is published should be included, as well as any notes or
 *gotchas* in the code to watch out for.
 #. When writing a header file that may be ``#include``\d by a C source file.
 #. When writing a source file that is used by a tool that only accepts C style
 comments.
-To comment out a large block of code, use ``#if 0`` and ``#endif``. These nest
+Commenting out large blocks of code is discouraged, but if you really have to do
-properly and are better behaved in general than C style comments.
+this (for documentation purposes or as a suggestion for debug printing), use
+``#if 0`` and ``#endif``. These nest properly and are better behaved in general
+than C style comments.
 Doxygen Use in Documentation Comments
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 Use the ``\file`` command to turn the standard file header into a file-level
 comment.
 Include descriptive paragraphs for all public interfaces (public classes,
 member and non-member functions).  Don't just restate the information that can
-be inferred from the API name.  The first sentence or a paragraph beginning
+be inferred from the API name.  The first sentence (or a paragraph beginning
-with ``\brief`` is used as an abstract. Put detailed discussion into separate
+with ``\brief``) is used as an abstract. Try to use a single sentence as the
+``\brief`` adds visual clutter.  Put detailed discussion into separate
 paragraphs.
 To refer to parameter names inside a paragraph, use the ``\p name`` command.
 Don't use the ``\arg name`` command since it starts a new paragraph that
 contains documentation for the parameter.
 A documentation comment that uses all Doxygen features in a preferred way:
 .. code-block:: c++
-/// \brief Does foo and bar.
+/// Does foo and bar.
 ///
 /// Does not do foo the usual way if \p Baz is true.
 ///
 /// Typical usage:
 /// \code
 .. _Main Module Header:
 .. _Local/Private Headers:
 #. Main Module Header
 #. Local/Private Headers
-#. ``llvm/...``
+#. LLVM project/subproject headers (``clang/...``, ``lldb/...``, ``llvm/...``, etc)
 #. System ``#include``\s
 and each category should be sorted lexicographically by the full path.
 The `Main Module Header`_ file applies to ``.cpp`` files which implement an
 **first** regardless of where it lives on the file system.  By including a
 header file first in the ``.cpp`` files that implement the interfaces, we ensure
 that the header does not have any hidden dependencies which are not explicitly
 ``#include``\d in the header, but should be. It is also a form of documentation
 in the ``.cpp`` file to indicate where the interfaces it implements are defined.
+LLVM project and subproject headers should be grouped from most specific to least
+specific, for the same reasons described above.  For example, LLDB depends on
+both clang and LLVM, and clang depends on LLVM.  So an LLDB source file should
+include ``lldb`` headers first, followed by ``clang`` headers, followed by
+``llvm`` headers, to reduce the possibility (for example) of an LLDB header
+accidentally picking up a missing include due to the previous inclusion of that
+header in the main source file or some earlier header file.  clang should
+similarly include its own headers before including llvm headers.  This rule
+applies to all LLVM subprojects.
 .. _fit into 80 columns:
 Source Code Width
 ^^^^^^^^^^^^^^^^^
 Factory<Tire> Factory;      // Better.
 Factory<Tire> TireFactory;  // Even better -- if VehicleMaker has more than one
 // kind of factories.
 };
-Vehicle MakeVehicle(VehicleType Type) {
+Vehicle makeVehicle(VehicleType Type) {
 VehicleMaker M;                         // Might be OK if having a short life-span.
 Tire Tmp1 = M.makeTire();               // Bad -- 'Tmp1' provides no information.
 Light Headlight = M.makeLight("head");  // Good -- descriptive.
 ...
 }

Mercurial > hg > CbC > CbC_llvm

comparison docs/CodingStandards.rst @ 120:1172e4bd9c6f