-
Notifications
You must be signed in to change notification settings - Fork 118
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
Add --include-src-dir option to enable generating docs for files in lib/src #664
Comments
The files in the |
Maybe we need an option to generate docs for libraries inside of src/ , which might be useful for people generating docs for their own use? (If libraries are in src/ they can be used by the library developer.) |
What problem are you seeing with dartdocgen? It's still being used to On Thu, Jul 16, 2015 at 5:50 AM Jana Moudrá notifications@github.com
|
FileSystemException: Cannot find SDK directory starting from , path = '/usr/local/Cellar/dart/1.11.1/libexec/bin/snapshots' (Found out, that it doesn't work until the dartdoc-viewer folder is deleted. I didn't have problem with this before). Problem is also here: dart-lang/homebrew-dart#16 |
@Janamou maybe open an issue over here? https://github.com/dart-lang/sdk |
OK, it doesn't understand that layout. dartdocgen --sdk usr/local/Cellar/dart/1.11.1 or wherever the SDK directory is located, might work. On Thu, Jul 16, 2015 at 10:07 AM Jana Moudrá notifications@github.com
|
It's probably not too uncommon to want to generate docs for a "private" API of a package/library. We might want to add some sort of --include-src-libs as an opt-in option. If we do that, we'll probably want to mark those libraries explicitly as "implementation only" or similar, so it's clear it's not part of the public API. |
@alan-knight thanks, I solved this by deleting the dartdoc-viewer folder. |
Unfortunately, we don't plan to address this in the near future. However, it might make sense to add a --include-src-dir option, so you can opt-in. How does that sound? |
@sethladd sounds great! :-) |
Libraries in src are considered private as per https://www.dartlang.org/tools/pub/package-layout.html#implementation-files. However, it's my understanding that it's convention to place library 'part' dart files in src. Example: utilities.dart
Classes and functions in src/string_utils.dart and src/date_utils.dart are part of the public api of the utilities library, and docs should be generated for them. src/string_utils.dart
dartdoc should process files referred to in part declarations by default, whichever directory they are in. |
If a part from src/ is included in a library from lib/ , the contents of the part should be visible. Do you have an example of where that is not happening? |
Formally reproducing the problem lead me to realize that documentation is in fact being created for my library parts in src/ but I was mislead by a couple of things. My code is here: https://github.com/ArgentiApparatus/poisson_disc at today's commit (2f0136b3c498039d35ee94fec08441e51fd24aea). The library file /lib/poisson_disc.dart does not have any dartdoc comments in it, but the part file lib/src/bridson2.dart does. Output from dartdoc:
The message 'warning: library 'poisson_disc' has no documentation' is somewhat misleading. Also the screen capture shows the message 'library not documented' Not something I'd vehemently demand a fix for, but those messages perhaps should not be there if there is any dartdoc commentary somewhere in the library. |
@ArgentiApparatus , glad to see that dartdoc is working as is supposed to. Agree with you that showing |
Thanks for trying to reproduce it! "The message 'warning: library 'poisson_disc' has no documentation' is somewhat misleading." -- it maybe a tiny bit misleading, but it's not inaccurate :) I just checked your code, and the library itself doesn't have docs. Your package has docs (the README), and your classes have docs, but your library isn't documentated. Maybe there's a better way to say it. Any suggestions? (if so, please open a new bug) Also, we could debate if that warning makes any sense. (again, let's do that in another bug) Thanks for the feedback! |
Hello, Thanks in advance :-) |
Sorry for the extreme delay in responding. There is an --include-external parameter that should enable you to specify libraries in lib/src. Dartdoc essentially is trying to implement the pub conventions for dart packages in terms of what is part of the public interface to a package and what isn't. There probably could be a flag that says "document private interfaces too" for people who want that and we could highlight that the documented model element is private in some way in the generated HTML. |
There's still no option in dartdoc to include comments on private classes, methods and fields into the doc. Very needed indeed. Is there an option to downgrade the dart sdk to use dartdocgen, which supported the doc generation for private instances? |
I support this feature as well. In my project, an app, dartdoc is used to help inform future maintainers. In this case, there is no sense of "private" classes -- everything needs to be documented and transparent. an |
I don't object to this feature being added if someone wants to take it on, but it seems unlikely that I'll get to it soon. |
This would be great especially for working in Monorepos where you would like to have one point of entry for the whole documentation |
This is being tracked in #3096 and can probably be closed in favor of that one. I have some time in the near future to work on it but all my code so far is in a PR (#3097) if anyone wants. So far, it's working in some cases and tests have to be reconfigured to expect private documentation when requested. |
Hi,
I love the dartdoc, it is much faster and nicer than dartdocgen but I have problem with generating documentation from libraries inside src/ folder. This folder is simply omitted.
This thing was also "feature" of dartdocgen but I hacked it in a way that I listed all the .dart files from lib/ folder including those in src/ folder and then ran the command:
dartdocgen --serve lib/src/file1.dart lib/src/file2.dart
etc.But I can't pass .dart file to dartdoc in a same style :-(
Is there any way how I can do this?
P.S.: I can't use dartdocgen with the latest Dart sdk (1.11.1) version (it has again problem with SDK).
The text was updated successfully, but these errors were encountered: