Add --include-src-dir option to enable generating docs for files in lib/src

[Janamou]

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

[keertip]

The files in the src folder are considered to be private and not part of the public api, which is why dartdoc excludes those files. If you export these libraries and make them part of the api, then dartdoc will generate docs for them. dartdoc does not have an option to specify files.

[sethladd]

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

[alan-knight]

What problem are you seeing with dartdocgen? It's still being used to
generate api.dartlang.org and the content at dartdocs.org, so it ought to
be able to work with the SDK. And if it isn't, we still need to fix it
until dartdocs is fully deployed.

On Thu, Jul 16, 2015 at 5:50 AM Jana Moudrá notifications@github.com
wrote:

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

—
Reply to this email directly or view it on GitHub
#664.

[Janamou]

dartdocgen
Works, shows help.

dartdocgen ., dartdocgen lib, dartdocgen lib/some_dart_file.dart
Throws exception:

FileSystemException: Cannot find SDK directory starting from , path = '/usr/local/Cellar/dart/1.11.1/libexec/bin/snapshots'
#0 rootDirectory (file:///Volumes/data/b/build/slave/dart-sdk-mac-stable/build/sdk/pkg/docgen/lib/src/package_helpers.dart:32)
#1 ensureMovedViewerCode (file:///Volumes/data/b/build/slave/dart-sdk-mac-stable/build/sdk/pkg/docgen/lib/src/viewer.dart:70)
#2 docgen (file:///Volumes/data/b/build/slave/dart-sdk-mac-stable/build/sdk/pkg/docgen/lib/docgen.dart:50)
#3 main (file:///Volumes/data/b/build/slave/dart-sdk-mac-stable/build/sdk/pkg/docgen/bin/docgen.dart:43)
#4 main (file:///Volumes/data/b/build/slave/dart-sdk-mac-stable/build/sdk/xcodebuild/DerivedSources/ReleaseX64/utils_wrapper.dart:12)
#5 _startIsolate. (dart:isolate-patch/isolate_patch.dart:259)
#6 _RawReceivePortImpl._handleMessage (dart:isolate-patch/isolate_patch.dart:148)

(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

[sethladd]

@Janamou maybe open an issue over here? https://github.com/dart-lang/sdk

[alan-knight]

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
wrote:

dartdocgen
Works, shows help.

dartdocgen ., dartdocgen lib, dartdocgen lib/some_dart_file.dart
Throws exception:

FileSystemException: Cannot find SDK directory starting from , path =
'/usr/local/Cellar/dart/1.11.1/libexec/bin/snapshots'
#0 rootDirectory
(file:///Volumes/data/b/build/slave/dart-sdk-mac-stable/build/sdk/pkg/docgen/lib/src/package_helpers.dart:32)
#1 #1 ensureMovedViewerCode
(file:///Volumes/data/b/build/slave/dart-sdk-mac-stable/build/sdk/pkg/docgen/lib/src/viewer.dart:70)
#2 #2 docgen
(file:///Volumes/data/b/build/slave/dart-sdk-mac-stable/build/sdk/pkg/docgen/lib/docgen.dart:50)
#3 #3 main
(file:///Volumes/data/b/build/slave/dart-sdk-mac-stable/build/sdk/pkg/docgen/bin/docgen.dart:43)
#4 #4 main
(file:///Volumes/data/b/build/slave/dart-sdk-mac-stable/build/sdk/xcodebuild/DerivedSources/ReleaseX64/utils_wrapper.dart:12)
#5 #5 _startIsolate.
(dart:isolate-patch/isolate_patch.dart:259)
#6 #6
_RawReceivePortImpl._handleMessage
(dart:isolate-patch/isolate_patch.dart:148)

(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
dart-lang/homebrew-dart#16

—
Reply to this email directly or view it on GitHub
#664 (comment).

[sethladd]

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.

[Janamou]

@alan-knight thanks, I solved this by deleting the dartdoc-viewer folder.
@sethladd this option would be nice :-)

[sethladd]

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?

[Janamou]

@sethladd sounds great! :-)

[ArgentiApparatus]

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

library utilities;
part "src/string_utils.dart";
part "src/date_utils.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

String reverseString(s) { ... } // Part of utilities library public api
...

dartdoc should process files referred to in part declarations by default, whichever directory they are in.

[sethladd]

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?

[ArgentiApparatus]

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:

PS C:\Users\xxx\poisson_disc> dart --version
Dart VM version: 1.12.1 (Tue Sep 08 04:22:07 2015) on "windows_x64"
PS C:\Users\xxx\poisson_disc>


PS C:\Users\xxx\poisson_disc> pub get
Resolving dependencies...
+ vector_math 1.4.3
Changed 1 dependency!
Precompiling executables...
Loading source assets...
A transformer imported unknown package "benchmark_harness" (in "package:benchmark_harness/benchmark_harness.dart").

PS C:\Users\xxx\poisson_disc> dartdoc
Generating documentation for 'poisson_disc' into C:\Users\xxx\poisson_disc\doc\api\

parsing lib\poisson_disc.dart...
Parsed 1 file in 5.7 seconds.

generating docs for library poisson_disc from poisson_disc.dart...
warning: library 'poisson_disc' has no documentation
Documented 1 library in 6.4 seconds.

Success! Open file://C:\Users\xxx\poisson_disc\doc\api/index.html

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.

[keertip]

@ArgentiApparatus , glad to see that dartdoc is working as is supposed to. Agree with you that showing library not documented can be misleading.

[sethladd]

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!

[ArgentiApparatus]

@sethladd Yep, I noted my library lacks top level docs, and understand the current behavior is technically correct.

New issue #949.

[jox81]

Hello,
I know this issues have been opened for a long time but now the dart convention is to suppress the part of and the library keyword. So then, how to reproduce the dartdoc generation of the files inside the lib/src folders without creating a public file with all the parts ?

Thanks in advance :-)

[jcollins-g]

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.

[245879345]

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?

[Levi-Lesches]

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 --include-src-dir or --internal flag would be greatly appreciated. Using --include-external for every single file is obviously not an optoion.

[jcollins-g]

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.

[dkbast]

This would be great especially for working in Monorepos where you would like to have one point of entry for the whole documentation

[Levi-Lesches]

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.