Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Prior doc comments #2374

Closed
wants to merge 1 commit into from
Closed

Prior doc comments #2374

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 94 additions & 0 deletions text/0000-prior-doc-comment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
- Feature Name: prior_doc_comment
- Start Date: 2018-03-26
- RFC PR: (leave this empty)
- Rust Issue: (leave this empty)

# Summary
[summary]: #summary

Allow `//!` (also called "outer doc comments" below) to be used to annotate the block just prior to them.

# Motivation
[motivation]: #motivation

This usecase, where the doc comment is put after an enum variant, is likely to be most widely used:

```rust
enum E {
/// doc comments used currently
A,
B, //! doc comments with this RFC
Copy link
Contributor

@Centril Centril Mar 27, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's possible to do this in Haskell with haddock like so (which you can mention in the Prior art if you like):

data Maybe a
  = Nothing -- ^ There is nothing here.
  | Just a  -- ^ We have a measly 'a'.

But I'm skeptical that this enhances readability for Rust. At least, if this is possible, I would like it to not be the recommended style by rustfmt.

This sparked an orthogonal question in my mind... What if we allowed the following:

fn foo(x: usize,  //! Some comments about x
       y: String, //! Some comments about y
     ) -> Result  //! Comments about return values.
{
    unimplemented!()
}

or in Haskell:

foo :: Int    -- ^ Some comments about x
    -> String -- ^ Some comments about y
    -> Result -- ^ Comments about return values.
foo x y = undefined

I guess using //! in this way makes sense in that case.

Copy link

@ExpHP ExpHP Mar 28, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not too keen on the return value. Mind the way this would most likely work is:

fn foo(x: usize,  //! Some comments about x
       y: String, //! Some comments about y
     ) -> Result  //! Comments about return values.
{ }

fn foo(x: usize,  //! Some comments about x
       y: String, //! Some comments about y
     ) -> Result;  //! Comments about the... hey, wait a second, you
                   //! pesky semicolon! This is actually documenting the
                   //! entire fn item, isn't it?!

unless you want to propose serious changes (I think) to how rust tokenizes things.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think we would be introducing param documents immediately. Instead, I imagine if this will even be a part of this RFC, it will be just concatenated and we'll leave parameter description boilerplates up to the document author.

C,
}
```

There are also people who prefer documentation after member. See [1](https://capnproto.org/language.html#comments) [2](https://internals.rust-lang.org/t/any-interest-in-same-line-doc-comments/3212).

# Guide-level explanation
[guide-level-explanation]: #guide-level-explanation

`//!` can be used to document the enclosing block, and with this RFC can be used to document the prior block.

For example:

```
enum Option<T> {
//! The `Option` type. See [the module level documentation](index.html) for more.
None, //! No value
Some(T), //! Some value `T`
}
```

# Reference-level explanation
[reference-level-explanation]: #reference-level-explanation

`//!` Documentation comments are now allowed after the identifier, and can be separated by a combination of whitespace or newlines.

When there are both `///` and `//!` blocks, the doc comments are concatenated in order.

It will be valid to interleave the two style of comments, although this is not a thing we want to do and we may issue an warning:

```
enum E {
//! A
/// B
//! C
/// D
X,
//! E
}
```

The documentation for `enum E` will be:
```
A
C
```

and the documentation for `E::X` will be:
```
B
D
E
```

# Drawbacks
[drawbacks]: #drawbacks

Rust have limited doc comment syntax for the sake of simplicity. While this RFC doesn't propose any new syntax, this may complicate the learning of Rust.

# Rationale and alternatives
[alternatives]: #alternatives

TBD. This RFC is designed to be very conservative.

# Prior art
[prior-art]: #prior-art

As mentioned in [motivation], [Cap'n Proto](https://capnproto.org/language.html#comments) has been recommending this as default
and [Doxygen](http://www.stack.nl/~dimitri/doxygen/manual/docblocks.html#memberdoc) has the support of such comments.

# Unresolved questions
[unresolved]: #unresolved-questions

TBD