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.