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
Comments
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. |
Am I right in reading that the current spec only allows a single token in a code section? Is this valid: |
It is valid. |
Am I reading the spec wrong? I see:
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:
I would assume 1 + 2 is three tokens, so I don't see how 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? |
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. |
Removed this from the 1.6 milestone. |
Removed Oldschool-Milestone-1.6 label. |
We use Markdown for doc comments now. |
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).
The text was updated successfully, but these errors were encountered: