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

Need ability to create library-level API docs without an explicit library tag. #1082

Open
Sfshaza opened this issue Jan 13, 2016 · 21 comments
Open
Labels

Comments

@Sfshaza
Copy link

@Sfshaza Sfshaza commented Jan 13, 2016

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.

@keertip
Copy link
Contributor

@keertip keertip commented Jan 13, 2016

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!

@munificent
Copy link
Member

@munificent munificent commented Jan 13, 2016

After some discussion, the new proposed rule is simpler:

Use the first doc comment attached to any directive (import, export, etc.).

@keertip
Copy link
Contributor

@keertip keertip commented Jan 25, 2016

This fix has been made to the analyzer. Upgrading to new analyzer package, current 0.27.1+2, will fix this issue.

@devoncarew
Copy link
Member

@devoncarew devoncarew commented Jul 21, 2016

I think this is fixed?

@kwalrath
Copy link
Member

@kwalrath kwalrath commented Aug 7, 2018

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 dart-archive/stagehand#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

@kwalrath kwalrath reopened this Aug 7, 2018
@jcollins-g
Copy link
Collaborator

@jcollins-g jcollins-g commented Aug 7, 2018

You're right, we still require the library statement -- if it was fixed at one point, it was before I took over.

@jcollins-g
Copy link
Collaborator

@jcollins-g jcollins-g commented Aug 7, 2018

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.

@kwalrath
Copy link
Member

@kwalrath kwalrath commented Aug 8, 2018

Very strange. Thanks for looking into this. Please let me know if there's anything I can do to help.

@kwalrath kwalrath removed their assignment Aug 15, 2018
@natebosch
Copy link
Member

@natebosch natebosch commented Oct 3, 2018

Any update here?

@jcollins-g
Copy link
Collaborator

@jcollins-g jcollins-g commented Oct 3, 2018

AFAIK state has not changed.

@kevmoo
Copy link
Member

@kevmoo kevmoo commented Dec 9, 2020

I think we'd want this: dart-lang/language#1073

@jcollins-g
Copy link
Collaborator

@jcollins-g jcollins-g commented Dec 9, 2020

@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
Copy link
Member

@kevmoo kevmoo commented Dec 9, 2020

@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

@jcollins-g
Copy link
Collaborator

@jcollins-g jcollins-g commented Dec 9, 2020

@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.

@Levi-Lesches
Copy link

@Levi-Lesches Levi-Lesches commented Dec 9, 2020

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?

@jcollins-g
Copy link
Collaborator

@jcollins-g jcollins-g commented Dec 9, 2020

@Levi-Lesches No particular reason, other than the language needs to support having a library; statement with no name.

@Levi-Lesches
Copy link

@Levi-Lesches Levi-Lesches commented Dec 9, 2020

Yeah I totally agree -- so is that what you would expect a library; statement to do? The same as if it weren't there?

@kevmoo
Copy link
Member

@kevmoo kevmoo commented Dec 9, 2020

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.

@jcollins-g
Copy link
Collaborator

@jcollins-g jcollins-g commented Dec 9, 2020

@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.

@lrhn
Copy link
Member

@lrhn lrhn commented Dec 10, 2020

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
10 participants