dartdoc
dartdoc copied to clipboard
dart-lang
Need ability to create library-level API docs without an explicit library tag.
Bob suggests:
- If there is a doc before any declarations in the library
- and the doc comment is not directly (i.e. without a blank line) before the first declaration.
Then we treat that as the doc comment for the library.
dartdoc gets the doc comment for all elements from the analyzer. So analyzer would need to be modified to support getting doc comments from a dart file before the first declaration.
@Sfshaza, could you open a issue for the analyzer and link it in here? Thanks!
After some discussion, the new proposed rule is simpler:
Use the first doc comment attached to any directive (import, export, etc.).
This fix has been made to the analyzer. Upgrading to new analyzer package, current 0.27.1+2, will fix this issue.
I don't know if it was ever fixed.
I don't see any library comments for the stagehand docs unless I add a library statement (library stagehand;) above the imports. We removed the library statement in https://github.com/dart-lang/stagehand/pull/307 (3/2016), v1.0.2, and that's when the library comments disappeared from the dartdoc: 1.0.2 library docs, 1.0.1 library docs
You're right, we still require the library statement -- if it was fixed at one point, it was before I took over.
And I'm actually not right at all. This does work in dartdoc's internal tests to my surprise. Don't know why it doesn't work in your case, will require some investigation.
Very strange. Thanks for looking into this. Please let me know if there's anything I can do to help.
@kevmoo Note that we do recognize and generate docs for the library, this issue is a request to notice a comment block at the beginning of the file without a library tag and pretend it is a library documentation comment.
@kevmoo Note that we do recognize and generate docs for the library, this issue is a request to notice a comment block at the beginning of the file without a library tag and pretend it is a library documentation comment.
Yup. But I find a lot of folks are blocked on what to name their libraries. If it could just be "naked" so we'd have a place to hang things – it'd be nice.
Less guessing for things like dartdoc and test
@kevmoo The proposed solution in dart-lang/language#1073 (have a library tag with no name, e.g. library;) is the way I'd really prefer this to be solved. Of course, it means less work for me, but more seriously it's much less "mushy" and prone to failure in terms of accidentally changing comments in the header of the file to break a hacky mapping. If there's some data saying this is a big impact we or if we have critical users blocked and we can't wait for a language solution, will upgrade to P1.
If you don't include a library statement, then the library is implicitly named as the filename, right? Like main.dart would have an implicit library main. So why can't a "blank" library statement do the same thing?
@Levi-Lesches No particular reason, other than the language needs to support having a library; statement with no name.
Yeah I totally agree -- so is that what you would expect a library; statement to do? The same as if it weren't there?
Yeah I totally agree -- so is that what you would expect a
library;statement to do? The same as if it weren't there?
From my perspective, it eliminates hacks we have now to allow "floating" annotations – without having to think about the name of the library.
@Levi-Lesches Pretty much. The only difference would be the analyzer would be able to connect not only annotations but also documentation specifically to that statement, and therefore to returned LibraryElements for downstream tool consumers like dartdoc.
A library; declaration would do exactly the same thing as no library declaration, except that you could hang annotations and dartdoc on it. It's a declaration representing the library itself, like library foo.bar.baz;, but unlike the latter it doesn't also name the library.
A library with no library declaration has the empty name, and library; would also give the library the empty name.
Another workaround for libraries that don't have any imports would be to add a seemingly unnecessary import 'dart:core'; line.
Regarding a bare library; statement: could it be even more implicit? I think it seems unintuitive for library authors to be expected to add a library statement to hang dartdoc documentation on. IMO a blank line would be even better. If there's a dartdoc comment before the first definition but that's separated by a blank line, could the analyzer instead pretend that there is an implicit library statement that's based on the filename?
You're suggesting that in a file with no library declaration, the last "empty line" (probably not counting lines containing comments or comment delimiters, or a leading script tags, but possibly counting a line containing only a BOM and plain whitespace characters) which precedes the first actual declaration, would be treated as am implicit library; declaration, and any comment or metadata above that line would attach to the implicit library declaration.
That's ... not impossible. It's more significance than we usually assign to whitespace (which is "none, whatsoever"), but it's also against normal style rules/formatter dictate to have empty lines between metadata and what they annotate. That means that it usually won't happen by acccident (and if it does, the formatter will retain that empty line so you can see that something is going on.)
I'm not sold on the idea ("prefer explicit to implicit" etc.), but if that is what people really want, and our parser and formatter people think they can handle it, then it's probably acceptable.
The failure mode is to accidentally add an empty line between an annotation and the import (or other declaration, if you have no imports) that it's intended to annotate, and then nothing warns you that it's not where it's supposed to be.
I think it seems unintuitive for library authors to be expected to add a
librarystatement to hang dartdoc documentation on. IMO a blank line would be even better.
I think the implicit behavior would not as easy to learn as a line with library;. I think having the metadata and comments on an explicit declaration will make it easier for both humans and tools to work with.
I think the implicit behavior would not as easy to learn as a line with
library;. I think having the metadata and comments on an explicit declaration will make it easier for both humans and tools to work with.
While library; might be easy to learn, it'd still be something to learn. I suspect that many people don't know what library does. In contrast, I think that documenting a library with:
/// My library.
/// My function.
void foo() {}
is much more natural (and wouldn't require changes to the language spec).
I tend to agree with the principle of explicit rather than implicit -- having special, magical behavior for docs is something we want to move away from rather than add to.
To deal with the "something to learn" problem, I could imagine a lint that detects the example @jamesderlin mentions and redirects users to use a bare library; tag.
the principle of explicit rather than implicit [...] special, magical behavior for docs
IMHO the rule that first doc-comment block in the file followed by a blank line is-a library description is not at all magic, it feels natural. While sourcing the docs heading name from the file's name is a bit magic, it also is not that uncommon in other languages. Then "add a library your_chosen_name; tag to override the default name" would be a knowledge that authors will easily find had they come to conclusion they would rather had other name.
If it should be explicit, I would suggest use yet more explicit library _; where underscore is explained as "take name to display from the import path".
Seems the choice was to go for an empty library; tag which allows documentation as well as library-level annotations. Support is now implemented in the Dart 2.19 dev releases: https://github.com/dart-lang/language/issues/1073
Tracking new documentation in https://github.com/dart-lang/site-www/issues/4314
