Selaa lähdekoodia

Added design of comments in design docs (#2641)

The [Comments #198](https://github.com/carbon-language/carbon-lang/pull/198) got accepted but the details were not updated in the design docs. Added `comments.md` file to add the details of the proposal and its discussion.

Closes #1994
Aswin Shailajan 3 vuotta sitten
vanhempi
sitoutus
33f26bd37b

+ 2 - 1
docs/design/lexical_conventions/README.md

@@ -27,7 +27,8 @@ A _lexical element_ is one of the following:
 -   a literal:
     -   a [numeric literal](numeric_literals.md)
     -   a [string literal](string_literals.md)
--   TODO: operators, comments, ...
+-   a [comment](comments.md)
+-   TODO: operators ...
 
 The sequence of lexical elements is formed by repeatedly removing the longest
 initial sequence of characters that forms a valid lexical element.

+ 58 - 0
docs/design/lexical_conventions/comments.md

@@ -0,0 +1,58 @@
+# Comments
+
+<!--
+Part of the Carbon Language project, under the Apache License v2.0 with LLVM
+Exceptions. See /LICENSE for license information.
+SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+-->
+
+<!-- toc -->
+
+## Table of contents
+
+-   [Overview](#overview)
+-   [Details](#details)
+-   [Alternatives considered](#alternatives-considered)
+-   [References](#references)
+
+<!-- tocstop -->
+
+## Overview
+
+A comment is a lexical element beginning with the characters `//` and running to
+the end of the line. We have no mechanism for physical line continuation, so a
+trailing `\` does not extend a comment to subsequent lines.
+
+## Details
+
+In the comments after the `//` a whitespace character is required to make the
+comment valid. Newline is a whitespace character, so a line containing only `//`
+is a valid comment. The end of the file also constitutes whitespace.
+
+All comments are removed prior to formation of tokens.
+
+Example:
+
+```
+// This is a comment and is ignored. \
+This is not a comment.
+
+var Int: x; // error, trailing comments not allowed
+```
+
+Currently no support for block comments is provided. Commenting out larger
+regions of human-readable text or code is accomplished by commenting out every
+line in the region.
+
+## Alternatives considered
+
+-   [Intra-line comments](/proposals/p0198.md#intra-line-comments)
+-   [Multi-line text comments](/proposals/p0198.md#multi-line-text-comments)
+-   [Block comments](/proposals/p0198.md#block-comments-2)
+-   [Documentation comments](/proposals/p0198.md#documentation-comments)
+-   [Code folding comments](/proposals/p0198.md#code-folding-comments)
+
+## References
+
+-   Proposal
+    [#198: Comments](https://github.com/carbon-language/carbon-lang/pull/198)