From 5b17b4ea2b693aac82d4a0c38b7a4f68e700ced5 Mon Sep 17 00:00:00 2001 From: Paul Robinson Date: Thu, 22 Jan 2015 00:19:56 +0000 Subject: [PATCH] Explicitly describe '///' versus '//' comment delimiters. git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@226750 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/CodingStandards.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/CodingStandards.rst b/docs/CodingStandards.rst index 0552c7117e2..f5e07bd499d 100644 --- a/docs/CodingStandards.rst +++ b/docs/CodingStandards.rst @@ -251,7 +251,8 @@ The next section in the file is a concise note that defines the license that 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 describing the purpose of the file. It +The main body is a ``doxygen`` comment (identified by the ``///`` comment +marker instead of the usual ``//``) 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 @@ -281,7 +282,8 @@ happens: does the method return null? Abort? Format your hard disk? Comment Formatting ^^^^^^^^^^^^^^^^^^ -In general, prefer C++ style (``//``) comments. They take less space, require +In general, prefer C++ style comments (``//`` for normal comments, ``///`` for +``doxygen`` documentation comments). They take less space, require less typing, don't have nesting problems, etc. There are a few cases when it is useful to use C style (``/* */``) comments however: -- 2.34.1