Expand documentation of dart doc
#5494
Conversation
parlough
changed the title
dart doc
|
Visit the preview URL for this PR (updated for commit 6f97a83): https://dart-dev--pr5494-feat-expanded-dart-doc-docs-lpxu7nra.web.app |
parlough
force-pushed
the
feat/expanded-dart-doc-docs
branch
from
87fb78b to
2b9a010
Compare
parlough
force-pushed
the
feat/expanded-dart-doc-docs
branch
from
2b9a010 to
2c1cee8
Compare
src/tools/dart-doc.md
Outdated
| `dart doc` is also used to generate the API reference documentation for | ||
| the Dart core libraries. |
There was a problem hiding this comment.
issue: Condition, then instruction per GSG.
| `dart doc` is also used to generate the API reference documentation for | |
| the Dart core libraries. | |
| To generate the API documentation for the Dart core libraries, | |
| you can also use `dart doc`. |
There was a problem hiding this comment.
This isn't something end-users (generally) do. This is something that's done by the SDK release infrastructure. I'm trying to draw attention to the fact that the SDK's own API docs use the same tooling. Then lead into how to view it (next sentence).
Any suggestions considering that context?
src/tools/dart-doc.md
Outdated
| The following are some common issues experienced with | ||
| documentation generated using `dart doc`, | ||
| as well as suggestions to resolve them. | ||
|
|
There was a problem hiding this comment.
issue: The following sentences should be simplified. Make them more concise. Also, consider changing the problems and solutions into tables. That would make it easier to skim.
There's also instances of passive voice, redundancy, and equivocation.
Passive voice, sentence is too long, command can't be used as a noun.
The `index.json` file generated by `dart doc` is missing or inaccessible
from the documentation directory or your hosted web server.Passive voice, command can't be used as a noun.
The URL you are trying to access has incorrect capitalization.
The filenames generated by `dart doc` are case-sensitive,
match the source declarations, and by default have a `.html` extension.Redundant.
This configuration option is deprecated and set for removal.There was a problem hiding this comment.
Thanks for the suggestions here!
I'd like to keep these as distinct headers as I plan to link to them directly from tooling where appropriate. If a user isn't using those links to find them, the headers either in the TOC or through searching will likely be how users find these.
However I'll work on some updates to address your copy suggestions. After that, let me know if you think any further modifications are necessary. Thanks :D
There was a problem hiding this comment.
I made some initial adjustments here, but I likely could use some additional guidance, especially for some active voice adjustments. In a few of these cases, there's intentionally no actor as it's trying to non-prescriptively describe that a situation happened to something (like a file).
Thanks for your help here! It's a difficult part for me :)
Co-authored-by: Anthony Sansone <atsansone@users.noreply.github.com>
Contributes to dart-lang/sdk#54721 and dart-lang#4347 --------- Co-authored-by: Anthony Sansone <atsansone@users.noreply.github.com>
Contributes to dart-lang/sdk#54721 and dart-lang#4347 --------- Co-authored-by: Anthony Sansone <atsansone@users.noreply.github.com>
Contributes to dart-lang/sdk#54721 and #4347
Staged: https://dart-dev--pr5494-feat-expanded-dart-doc-docs-lpxu7nra.web.app/tools/dart-doc