llvm.org GIT mirror llvm / 1cf942c
Doxygen: Enable autobrief feature and update coding standards. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@237417 91177308-0d34-0410-b5e6-96231b3b80d8 Matthias Braun 4 years ago
2 changed file(s) with 17 addition(s) and 16 deletion(s). Raw diff Collapse all Expand all
246246 //===----------------------------------------------------------------------===//
247247 ///
248248 /// \file
249 /// \brief This file contains the declaration of the Instruction class, which is
250 /// the base class for all of the VM instructions.
249 /// This file contains the declaration of the Instruction class, which is the
250 /// base class for all of the VM instructions.
251251 ///
252252 //===----------------------------------------------------------------------===//
253253
267267 code can be distributed under and should not be modified in any way.
268268
269269 The main body is a ``doxygen`` comment (identified by the ``///`` comment
270 marker instead of the usual ``//``) describing the purpose of the file. It
271 should have a ``\brief`` command that describes the file in one or two
272 sentences. Any additional information should be separated by a blank line. If
273 an algorithm is being implemented or something tricky is going on, a reference
270 marker instead of the usual ``//``) describing the purpose of the file. The
271 first sentence or a passage beginning with ``\brief`` is used as an abstract.
272 Any additional information should be separated by a blank line. If an
273 algorithm is being implemented or something tricky is going on, a reference
274274 to the paper where it is published should be included, as well as any notes or
275275 *gotchas* in the code to watch out for.
276276
319319 Use the ``\file`` command to turn the standard file header into a file-level
320320 comment.
321321
322 Include descriptive ``\brief`` paragraphs for all public interfaces (public
323 classes, member and non-member functions). Explain API use and purpose in
324 ``\brief`` paragraphs, don't just restate the information that can be inferred
325 from the API name. Put detailed discussion into separate paragraphs.
322 Include descriptive paragraphs for all public interfaces (public classes,
323 member and non-member functions). Don't just restate the information that can
324 be inferred from the API name. The first sentence or a paragraph beginning
325 with ``\brief`` is used as an abstract. Put detailed discussion into separate
326 paragraphs.
326327
327328 To refer to parameter names inside a paragraph, use the ``\p name`` command.
328329 Don't use the ``\arg name`` command since it starts a new paragraph that
342343
343344 .. code-block:: c++
344345
345 /// \brief Does foo and bar.
346 void fooBar(bool Baz);
346 /// Sets the xyzzy property to \p Baz.
347 void setXyzzy(bool Baz);
347348
348349 A documentation comment that uses all Doxygen features in a preferred way:
349350
400401
401402 // In Something.h:
402403
403 /// \brief An abstraction for some complicated thing.
404 /// An abstraction for some complicated thing.
404405 class Something {
405406 public:
406 /// \brief Does foo and bar.
407 /// Does foo and bar.
407408 void fooBar();
408409 };
409410
168168 # description.)
169169 # The default value is: NO.
170170
171 JAVADOC_AUTOBRIEF = NO
171 JAVADOC_AUTOBRIEF = YES
172172
173173 # If the QT_AUTOBRIEF tag is set to YES then doxygen will interpret the first
174174 # line (until the first dot) of a Qt-style comment as the brief description. If
176176 # requiring an explicit \brief command for a brief description.)
177177 # The default value is: NO.
178178
179 QT_AUTOBRIEF = NO
179 QT_AUTOBRIEF = YES
180180
181181 # The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make doxygen treat a
182182 # multi-line C++ special comment block (i.e. a block of //! or /// comments) as