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.

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

Specify code blocks in doc comments #6375

Closed
munificent opened this issue Oct 29, 2012 · 13 comments
Closed

Specify code blocks in doc comments #6375

munificent opened this issue Oct 29, 2012 · 13 comments
Assignees
Labels
area-language New language issues should be filed at https://github.com/dart-lang/language needs-info We need additional information from the issue author (auto-closed after 14 days if no response) P2 A bug or feature request we're likely to work on type-bug Incorrect behavior (everything from a crash to more subtle misbehavior)

Comments

@munificent
Copy link
Member

The language spec describes:

> A token of the form [:code:] or code will render code as code in the formatted output.

But doesn't specify whether that's inline or or pre-formatted code. Presumably it's the former. In addition, users need to be able to specify pre-formatted blocks of code where whitespace is preserved. For example, see:

http://code.google.com/p/dart/source/browse/branches/bleeding_edge/dart/lib/compiler/implementation/compiler.dart#­884

http://code.google.com/p/dart/source/browse/branches/bleeding_edge/dart/pkg/unittest/unittest.dart

Markdown uses four spaces of indentation for this. Dartdoc supports that (with another space to separate the comment from the documentation).

@gbracha
Copy link
Contributor

gbracha commented Nov 7, 2012

Added this to the M2 milestone.
Added Accepted label.

@gbracha
Copy link
Contributor

gbracha commented Nov 28, 2012

This is a level of detail that belongs in tool documentation, not the language spec. I'm content to leave this as is and view it as a quality of implementation issue. If you can articulate spec-quality prose that describes the behavior, I'll consider adding it if it's not too long.


Added NeedsInfo label.

@munificent
Copy link
Member Author

Am I right in reading that the current spec only allows a single token in a code section? Is this valid: 1 + 2?

@gbracha
Copy link
Contributor

gbracha commented Nov 28, 2012

It is valid.

@munificent
Copy link
Member Author

Am I reading the spec wrong? I see:

Within a documentation comment, text is tokenized.

Does this mean we're tokenizing random human-language prose according to Dart's tokenization rules? Does this mean I can't use föo in a doc comment, even outside of code blocks?

Then I see:

A token of the form [:code:] or code will render code as code in the formatted output.

I would assume 1 + 2 is three tokens, so I don't see how 1 + 2 is valid. I'm having trouble understanding the spec here. I can read specs for programming languages, but a markup format is a very different thing, and I'm stuggling to see what the spec language is trying to express here.

Just to be clear, I don't personally care about what's in the spec for this at all. I'd be just as happy (likely happier) if it didn't specify doc comments at all. If, however, specifying anything means that functionality will be removed from dartdoc which our users are currently relying on, then I'm forced to care to maintain the usability of our docs.

Would it make sense for the spec to say additional unspecified formatting may be supported, or something open-ended like that?

If that's the case, it might be a reasonable compromise to have the spec describe how names inside [foo] are resolved (which definitely is something worth specifying) and then leave the rest out.

Thoughts?

@gbracha
Copy link
Contributor

gbracha commented Nov 29, 2012

The spec is a WIP, and the section on doc comments is by know means rigorous enough. It's not intended to be at this point - its not the top most priority at the moment. This will get more detailed over time. However, it is clear that we do not wish to commit to all the features now implemented by dartdoc in the spec.

The question of whether dartdoc can implement anything beyond the spec is a great topic for a future language meeting.

@gbracha
Copy link
Contributor

gbracha commented Dec 18, 2012

Removed this from the M2 milestone.
Added this to the M3 milestone.

@gbracha
Copy link
Contributor

gbracha commented Feb 15, 2013

Removed this from the M3 milestone.
Added this to the M4 milestone.

@gbracha
Copy link
Contributor

gbracha commented Apr 12, 2013

Removed this from the M4 milestone.
Added this to the M5 milestone.

@kasperl
Copy link

kasperl commented Jun 4, 2014

Removed this from the M5 milestone.
Added this to the 1.6 milestone.

@kasperl
Copy link

kasperl commented Jul 10, 2014

Removed this from the 1.6 milestone.
Added Oldschool-Milestone-1.6 label.

@kasperl
Copy link

kasperl commented Aug 4, 2014

Removed Oldschool-Milestone-1.6 label.

@munificent munificent added Type-Defect area-language New language issues should be filed at https://github.com/dart-lang/language needs-info We need additional information from the issue author (auto-closed after 14 days if no response) labels Aug 4, 2014
@kevmoo kevmoo added P2 A bug or feature request we're likely to work on type-bug Incorrect behavior (everything from a crash to more subtle misbehavior) and removed Priority-Medium labels Mar 1, 2016
@munificent
Copy link
Member Author

We use Markdown for doc comments now.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area-language New language issues should be filed at https://github.com/dart-lang/language needs-info We need additional information from the issue author (auto-closed after 14 days if no response) P2 A bug or feature request we're likely to work on type-bug Incorrect behavior (everything from a crash to more subtle misbehavior)
Projects
None yet
Development

No branches or pull requests

4 participants