deprecate and remove standalone dartdoc tool

[jcollins-g]

The dartdoc tool needs to be removed as a standalone tool in the SDK.

Checklist:

• 2.16 - Add new dart doc command: https://dart-review.googlesource.com/c/sdk/+/220744
• 2.16 - Add deprecation warning to bin/dartdoc: https://dart-review.googlesource.com/c/sdk/+/221948
• 2.17, beta 1 - Remove bin/dartdoc

---

Possible alternatives include:

1) Simply deprecating/deleting it and taking no further action, requiring users to use pub global activate dartdoc to install a package to document code. This is a straightforward approach that matches with recommended best practice for using dartdoc.
2) Deprecating the standalone tool, and replacing it with a wrapper inside dartdev that uses pub global activate internally to install dartdoc, then pass dartdoc the command line parameters.
3) Deprecating the standalone tool, and replacing it with a full version of dartdoc linked into dartdev as a library.

2 and 3 look largely the same to the user, 2 being more fragile and requiring network access but also more compact for SDK size.

My inclination is to go with option 1, funneling all users to the pub package.
edit: option 3 was chosen.

cc @mit-mit, @devoncarew, @bkonyi for input

[jcollins-g]

Adding area-build as well since dartdoc-in-the-SDK's most important user is the SDK build system itself.

[mit-mit]

My preference is option 3, which is what we're doing for other tools (dartfmt, analyzer, pub). I really like the consistency of that.

Yes, that has the disadvantage that it becomes a bit harder to use bleeding edge versions of dartdoc, as you have to wait for a roll, but looking at the global activate stats, I see less than 100 activates of dartdoc a week, which is a very small fraction of our overall user base.

[bkonyi]

+1 to option 3. We're trying our best to stay consistent and embed tooling into dartdev when it makes sense to. However, option 2 would allow for us to dynamically install dartdoc which has the nice property of not using extra disk space for users that never run the tool, which I think was an original goal for the CLI unification effort. Is that something we'd still be interesting in doing @mit-mit or did we shelve the idea for some particular reason?

[jcollins-g]

+1 for consistency -- will go for option 3 then unless there's a strong reason to do otherwise.

[mit-mit]

the nice property of not using extra disk space for users that never run the tool, which I think was an original goal for the CLI unification effort

Yes, that is correct, but that was more in the context of very large and rarely used features; say downloading an 100MB linker for building a custom embedder, og something like that.

[mit-mit]

@jcollins-g is there a known timeline for this deprecation?

[jcollins-g]

@mit-mit It is on the Q3 OKRs but not at a high priority (P2)

[jcollins-g]

Based on offline discussion, a proposed minimum list of command line parameters:

    --input                                       Path to source directory
                                                  (defaults to current working directory)
    --output                                      Path to output directory.
                                                  (defaults to "doc/api")
    --sdk-docs                                    Generate ONLY the docs for the Dart SDK.
    --[no-]validate-links                         Runs the built-in link checker to display Dart context aware warnings for broken links (slow)
                                                  (defaults to on)

You could use fork and exec, but I would suggest creating your own entry point modeled after https://github.com/dart-lang/dartdoc/blob/master/bin/dartdoc.dart. You might even be able to get dartdoc to handle help and all command line bits for you, at the expense of having a large surface area.

Let me know if you have any questions.

[mit-mit]

Thanks! What's the typical use for the --sdk-docs option? Is that something an app developer is likely to ever use?

[jcollins-g]

The typical use for the sdk docs option is to generate documentation for the SDK. A developer will use that if they want to check or modify docs for the SDK itself. It could be omitted if you want, especially since the pub package still exists.

[mit-mit]

I've started working on this in this CL:
https://dart-review.googlesource.com/c/sdk/+/217980

I have a test issue I'm hunting down with @bkonyi, but other than that it's pretty much done. I've done just the basic arg parsing:

$ dart  doc --help
Generate HTML API documentation from Dart documentation comments.

Usage: dart doc [arguments] <input directory>
-h, --help                   Print this usage information.
-o, --output-dir             Output directory (defaults to "doc/api)
                             (defaults to "./doc/api")
    --[no-]validate-links    Display context aware warnings for broken links (slow)

[mit-mit]

New CL in https://dart-review.googlesource.com/c/sdk/+/220744

[bkonyi]

The new changes LGTM. I'm assuming there's corresponding changes in dart-lang/dartdoc (maybe dart-lang/dartdoc#2857?)

[mit-mit]

I'm assuming there's corresponding changes in dart-lang/dartdoc

You, that issue you're linking needs to land first, then we'll roll dartdoc, and then my CL should work.

[mit-mit]

The new dart doc command has landed via https://dart-review.googlesource.com/c/sdk/+/220744 and was manually tested and confirmed working on Linux, macOS, and Windows with a bleeding edge build from http://gsdview.appspot.com/dart-archive/channels/be/raw/latest/sdk/

[mit-mit]

Deprecation message was added in https://dart-review.googlesource.com/c/sdk/+/221948

[mit-mit]

Discontinuation in https://dart-review.googlesource.com/c/sdk/+/228647

[DanTup]

@mit-mit is it intended/expected that the input directory is mandatory using the new command (but wasn't before)?

danny@Dannys-MacBook-Pro hello_world % ~/Dev/Dart\ SDKs/stable/bin/dartdoc 
Documenting hello_world...
-^C

danny@Dannys-MacBook-Pro hello_world % ~/Dev/Dart\ SDKs/nightly/bin/dart doc
Error: Input directory not specified

Usage: dart doc [arguments] <input directory>
-h, --help                   Print this usage information.
-o, --output-dir             Output directory
                             (defaults to "doc/api")
    --[no-]validate-links    Display context aware warnings for broken links (slow)

I noticed this while moving VS Code over. It's no bother for me to pass . (esp. since that works with both old and new) although it's more to type when invoking manually and seems like it could be inferred?

[mit-mit]

Yes, that is intentional. It was something we discussed a bit back and forth, and agreed to require given the command has a side effect that it changes the input directory (by writing a lot if files to it). This is consistent with the dart format command.

[DanTup]

Cool, just wanted to check it wasn't accidental. Thanks!