-
Notifications
You must be signed in to change notification settings - Fork 1.5k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Added design of comments in design docs (#2641)
The [Comments #198](#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
- Loading branch information
Showing
2 changed files
with
60 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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) |