Skip to content
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.

Sign up for GitHub

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

A few minor documentation updates #3641

Merged
merged 1 commit into from
Feb 5, 2024
Merged

A few minor documentation updates #3641

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 28 additions & 17 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,12 @@ For issues/details related to the hosted Dart SDK API docs, see

## Installation

The [`dart`](https://dart.dev/tools/dart-tool) tool,
with the `dart doc` command, is part of the [Dart SDK](https://dart.dev/get-dart).
The [`dart`][] tool, with the [`dart doc`][] command,
is part of the [Dart SDK][].

[`dart`]: https://dart.dev/tools/dart-tool
[`dart doc`]: https://dart.dev/tools/dart-doc
[Dart SDK]: https://dart.dev/get-dart

## Generating docs

Expand All @@ -39,26 +43,31 @@ Documented 1 public library in 17.9 seconds
Success! Docs generated into <path to dartdoc>/doc/api
```

By default, the documentation is generated to the `doc/api` directory as static
HTML files.
By default, the documentation is generated to the `doc/api` directory as
static HTML files.

To view the generated documentation, you must load them with an HTTP server.
To learn more, follow the [Viewing docs](#viewing-docs) guide.

Run `dart help doc` to see the available command-line options.

## Viewing docs

You can view the generated docs directly from the file system, but if you want
to use the search function, you must load them with an HTTP server.
To enable navigation and search, the generated docs must be
served with an HTTP server.

An easy way to run an HTTP server locally is to use the `dhttpd` package. For
example:
An easy way to run an HTTP server locally is to use [`package:dhttpd`][].
For example:

```
$ dart pub global activate dhttpd
$ dhttpd --path doc/api
$ dart pub global run dhttpd --path doc/api
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I made this change as I notice a lot of developers end up not adding the directory to their path. This is more likely to work :)

```

Navigate to `http://localhost:8080` in your browser; the search function should
now work.
To then read the generated docs in your browser,
open the link that `dhttpd` outputs, usually `http://localhost:8080`.

[`package:dhttpd`]: https://pub.dev/packages/dhttpd

## Link structure

Expand All @@ -83,16 +92,18 @@ File names are _case-sensitive_.

## Writing docs

Check out the
[Effective Dart: Documentation guide](https://dart.dev/guides/language/effective-dart/documentation).
To learn about writing documentation comments,
check out the [Effective Dart: Documentation guide][].

The guide covers formatting, linking, markup, and general best practices when
authoring doc comments for Dart with `dartdoc`.
authoring doc comments for Dart with `dart doc`.

[Effective Dart: Documentation guide]: https://dart.dev/effective-dart/documentation

## Excluding from documentation

`dart doc` will not generate documentation for a Dart element and its children that have the
`@nodoc` tag in the documentation comment.
`dart doc` will not generate documentation for a Dart element and
its children that have the `@nodoc` tag in the documentation comment.

## Advanced features

Expand Down Expand Up @@ -501,7 +512,7 @@ Please see the [dartdoc license][].
Generated docs include:

* Highlight.js -
[LICENSE](https://github.com/isagalaev/highlight.js/blob/main/LICENSE)
[LICENSE](https://github.com/highlightjs/highlight.js/blob/main/LICENSE)
* With `github.css` (c) Vasily Polovnyov <vast@whiteants.net>

[GitHub Issue Tracker]: https://github.com/dart-lang/dartdoc/issues
Expand Down
4 changes: 2 additions & 2 deletions doc/directives.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,8 @@ The supported directives are listed below:

## `@nodoc` - Do not include documentation

An element whose doc comment should not appear in the generated documenation can
include the `@nodoc` directive.
An element whose doc comment should not appear in the generated documentation
can include the `@nodoc` directive.

Note that the `@nodoc` directive does not have curly braces, like most of the
other directives.
Expand Down
18 changes: 16 additions & 2 deletions lib/resources/readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,20 @@
# highlight.js
# Dart documentation generator

Generated from https://highlightjs.org/download/ on 2021-07-13
This directory includes static sources used by the Dart documentation generator
through the `dart doc` command.

To learn more about generating and viewing the generated documentation,
check out the [`dart doc` documentation][].

[`dart doc` documentation]: https://dart.dev/tools/dart-doc

## Third-party resources

## highlight.js

Generated from https://highlightjs.org/download/ on 2021-07-13.

**License:** https://github.com/highlightjs/highlight.js/blob/main/LICENSE

**Included languages:**

Expand Down
Loading