Skip to content

Commit

Permalink
Added design of comments in design docs (#2641)
Browse files Browse the repository at this point in the history
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
aswin2108 authored Mar 30, 2023
1 parent 2c59dbc commit 33f26bd
Show file tree
Hide file tree
Showing 2 changed files with 60 additions and 1 deletion.
3 changes: 2 additions & 1 deletion docs/design/lexical_conventions/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 changes: 58 additions & 0 deletions docs/design/lexical_conventions/comments.md
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)

0 comments on commit 33f26bd

Please sign in to comment.