// License. See LICENSE.TXT for details.
//
//===----------------------------------------------------------------------===//
- //
- // This file contains the declaration of the Instruction class, which is the
- // base class for all of the VM instructions.
- //
+ ///
+ /// \file
+ /// \brief This file contains the declaration of the Instruction class, which is
+ /// the base class for all of the VM instructions.
+ ///
//===----------------------------------------------------------------------===//
A few things to note about this particular format: The "``-*- C++ -*-``" string
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 of the description does not have to be very long in most cases.
-Here it's only two lines. 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.
+The main body is a ``doxygen`` comment describing the purpose of the file. It
+should have a ``\brief`` command that describes the file in one or two
+sentences. 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.
Class overviews
"""""""""""""""
To comment out a large block of code, 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 ``\brief`` paragraphs for all public interfaces (public
+classes, member and non-member functions). Explain API use and purpose in
+``\brief`` paragraphs, don't just restate the information that can be inferred
+from the API name. 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.
+
+Wrap non-inline code examples in ``\code ... \endcode``.
+
+To document a function parameter, start a new paragraph with the
+``\param name`` command. If the parameter is used as an out or an in/out
+parameter, use the ``\param [out] name`` or ``\param [in,out] name`` command,
+respectively.
+
+To describe function return value, start a new paragraph with the ``\returns``
+command.
+
+A minimal documentation comment:
+
+.. code-block:: c++
+
+ /// \brief Does foo and bar.
+ void fooBar(bool Baz);
+
+A documentation comment that uses all Doxygen features in a preferred way:
+
+.. code-block:: c++
+
+ /// \brief Does foo and bar.
+ ///
+ /// Does not do foo the usual way if \p Baz is true.
+ ///
+ /// Typical usage:
+ /// \code
+ /// fooBar(false, "quux", Res);
+ /// \endcode
+ ///
+ /// \param Quux kind of foo to do.
+ /// \param [out] Result filled with bar sequence on foo success.
+ ///
+ /// \returns true on success.
+ bool fooBar(bool Baz, StringRef Quux, std::vector<int> &Result);
+
+Don't duplicate the documentation comment in the header file and in the
+implementation file. Put the documentation comments for public APIs into the
+header file. Documentation comments for private APIs can go to the
+implementation file. In any case, implementation files can include additional
+comments (not necessarily in Doxygen markup) to explain implementation details
+as needed.
+
+Don't duplicate function or class name at the beginning of the comment.
+For humans it is obvious which function or class is being documented;
+automatic documentation processing tools are smart enough to bind the comment
+to the correct declaration.
+
+Wrong:
+
+.. code-block:: c++
+
+ // In Something.h:
+
+ /// Something - An abstraction for some complicated thing.
+ class Something {
+ public:
+ /// fooBar - Does foo and bar.
+ void fooBar();
+ };
+
+ // In Something.cpp:
+
+ /// fooBar - Does foo and bar.
+ void Something::fooBar() { ... }
+
+Correct:
+
+.. code-block:: c++
+
+ // In Something.h:
+
+ /// \brief An abstraction for some complicated thing.
+ class Something {
+ public:
+ /// \brief Does foo and bar.
+ void fooBar();
+ };
+
+ // In Something.cpp:
+
+ // Builds a B-tree in order to do foo. See paper by...
+ void Something::fooBar() { ... }
+
+It is not required to use additional Doxygen features, but sometimes it might
+be a good idea to do so.
+
+Consider:
+
+* adding comments to any narrow namespace containing a collection of
+ related functions or types;
+
+* using top-level groups to organize a collection of related functions at
+ namespace scope where the grouping is smaller than the namespace;
+
+* using member groups and additional comments attached to member
+ groups to organize within a class.
+
+For example:
+
+.. code-block:: c++
+
+ class Something {
+ /// \name Functions that do Foo.
+ /// @{
+ void fooBar();
+ void fooBaz();
+ /// @}
+ ...
+ };
+
``#include`` Style
^^^^^^^^^^^^^^^^^^
.. code-block:: c++
- /// containsFoo - Return true if the specified list has an element that is
- /// a foo.
+ /// \returns true if the specified list has an element that is a foo.
static bool containsFoo(const std::vector<Bar*> &List) {
for (unsigned i = 0, e = List.size(); i != e; ++i)
if (List[i]->isFoo())
.. code-block:: c++
inline Value *getOperand(unsigned i) {
- assert(i < Operands.size() && "getOperand() out of range!");
+ assert(i < Operands.size() && "getOperand() out of range!");
return Operands[i];
}
supports the warning.
A knock-on effect of this stylistic requirement is that when building LLVM with
-GCC you may get warnings related "control may reach end of non-void function"
+GCC you may get warnings related to "control may reach end of non-void function"
if you return from each case of a covered switch-over-enum because GCC assumes
-that the enum expression may take any representable value, not just those in
-the enumeration. To suppress this warning, use ``llvm_unreachable`` after the
-switch.
+that the enum expression may take any representable value, not just those of
+individual enumerators. To suppress this warning, use ``llvm_unreachable`` after
+the switch.
Use ``LLVM_DELETED_FUNCTION`` to mark uncallable methods
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
namespace llvm {
namespace X86 {
- /// RelocationType - An enum for the x86 relocation codes. Note that
+ /// \brief An enum for the x86 relocation codes. Note that
/// the terminology here doesn't follow x86 convention - word means
/// 32-bit and dword means 64-bit.
enum RelocationType {
- /// reloc_pcrel_word - PC relative relocation, add the relocated value to
+ /// \brief PC relative relocation, add the relocated value to
/// the value already in memory, after we adjust it for where the PC is.
reloc_pcrel_word = 0,
- /// reloc_picrel_word - PIC base relative relocation, add the relocated
- /// value to the value already in memory, after we adjust it for where the
+ /// \brief PIC base relative relocation, add the relocated value to
+ /// the value already in memory, after we adjust it for where the
/// PIC base is.
reloc_picrel_word = 1,
- /// reloc_absolute_word, reloc_absolute_dword - Absolute relocation, just
- /// add the relocated value to the value already in memory.
+ /// \brief Absolute relocation, just add the relocated value to the
+ /// value already in memory.
reloc_absolute_word = 2,
reloc_absolute_dword = 3
};
namespace llvm {
namespace knowledge {
- /// Grokable - This class represents things that Smith can have an intimate
+ /// This class represents things that Smith can have an intimate
/// understanding of and contains the data associated with it.
class Grokable {
...
projects / oota-llvm.git / blobdiff