Bump the github-actions group with 3 updates (#4241) Bumps the github-actions group with 3 updates: [actions/upload-artifact](https://github.com/actions/upload-artifact), [github/codeql-action](https://github.com/github/codeql-action) and [actions/cache](https://github.com/actions/cache). Updates `actions/upload-artifact` from 7.0.0 to 7.0.1 <details> <summary>Release notes</summary> <p><em>Sourced from <a href="https://github.com/actions/upload-artifact/releases">actions/upload-artifact's releases</a>.</em></p> <blockquote> <h2>v7.0.1</h2> <h2>What's Changed</h2> <ul> <li>Update the readme with direct upload details by <a href="https://github.com/danwkennedy"><code>@danwkennedy</code></a> in <a href="https://redirect.github.com/actions/upload-artifact/pull/795">actions/upload-artifact#795</a></li> <li>Readme: bump all the example versions to v7 by <a href="https://github.com/danwkennedy"><code>@danwkennedy</code></a> in <a href="https://redirect.github.com/actions/upload-artifact/pull/796">actions/upload-artifact#796</a></li> <li>Include changes in typespec/ts-http-runtime 0.3.5 by <a href="https://github.com/yacaovsnc"><code>@yacaovsnc</code></a> in <a href="https://redirect.github.com/actions/upload-artifact/pull/797">actions/upload-artifact#797</a></li> </ul> <p><strong>Full Changelog</strong>: <a href="https://github.com/actions/upload-artifact/compare/v7...v7.0.1">https://github.com/actions/upload-artifact/compare/v7...v7.0.1</a></p> </blockquote> </details> <details> <summary>Commits</summary> <ul> <li><a href="https://github.com/actions/upload-artifact/commit/043fb46d1a93c77aae656e7c1c64a875d1fc6a0a"><code>043fb46</code></a> Merge pull request <a href="https://redirect.github.com/actions/upload-artifact/issues/797">#797</a> from actions/yacaovsnc/update-dependency</li> <li><a href="https://github.com/actions/upload-artifact/commit/634250c1388765ea7ed0f053e636f1f399000b94"><code>634250c</code></a> Include changes in typespec/ts-http-runtime 0.3.5</li> <li><a href="https://github.com/actions/upload-artifact/commit/e454baaac2be505c9450e11b8f3215c6fc023ce8"><code>e454baa</code></a> Readme: bump all the example versions to v7 (<a href="https://redirect.github.com/actions/upload-artifact/issues/796">#796</a>)</li> <li><a href="https://github.com/actions/upload-artifact/commit/74fad66b98a6d799dc004d3353ccd0e6f6b2530e"><code>74fad66</code></a> Update the readme with direct upload details (<a href="https://redirect.github.com/actions/upload-artifact/issues/795">#795</a>)</li> <li>See full diff in <a href="https://github.com/actions/upload-artifact/compare/bbbca2ddaa5d8feaa63e36b76fdaad77386f024f...043fb46d1a93c77aae656e7c1c64a875d1fc6a0a">compare view</a></li> </ul> </details> <br /> Updates `github/codeql-action` from 4.35.1 to 4.35.3 <details> <summary>Release notes</summary> <p><em>Sourced from <a href="https://github.com/github/codeql-action/releases">github/codeql-action's releases</a>.</em></p> <blockquote> <h2>v4.35.3</h2> <ul> <li><em>Upcoming breaking change</em>: Add a deprecation warning for customers using CodeQL version 2.19.3 and earlier. These versions of CodeQL were discontinued on 9 April 2026 alongside GitHub Enterprise Server 3.15, and will be unsupported by the next minor release of the CodeQL Action. <a href="https://redirect.github.com/github/codeql-action/pull/3837">#3837</a></li> <li>Configurations for private registries that use Cloudsmith or GCP OIDC are now accepted. <a href="https://redirect.github.com/github/codeql-action/pull/3850">#3850</a></li> <li>Best-effort connection tests for private registries now use <code>GET</code> requests instead of <code>HEAD</code> for better compatibility with various registry implementations. For NuGet feeds, the test is now always performed against the service index. <a href="https://redirect.github.com/github/codeql-action/pull/3853">#3853</a></li> <li>Fixed a bug where two diagnostics produced within the same millisecond could overwrite each other on disk, causing one of them to be lost. <a href="https://redirect.github.com/github/codeql-action/pull/3852">#3852</a></li> <li>Update default CodeQL bundle version to <a href="https://github.com/github/codeql-action/releases/tag/codeql-bundle-v2.25.3">2.25.3</a>. <a href="https://redirect.github.com/github/codeql-action/pull/3865">#3865</a></li> </ul> <h2>v4.35.2</h2> <ul> <li>The undocumented TRAP cache cleanup feature that could be enabled using the <code>CODEQL_ACTION_CLEANUP_TRAP_CACHES</code> environment variable is deprecated and will be removed in May 2026. If you are affected by this, we recommend disabling TRAP caching by passing the <code>trap-caching: false</code> input to the <code>init</code> Action. <a href="https://redirect.github.com/github/codeql-action/pull/3795">#3795</a></li> <li>The Git version 2.36.0 requirement for improved incremental analysis now only applies to repositories that contain submodules. <a href="https://redirect.github.com/github/codeql-action/pull/3789">#3789</a></li> <li>Python analysis on GHES no longer extracts the standard library, relying instead on models of the standard library. This should result in significantly faster extraction and analysis times, while the effect on alerts should be minimal. <a href="https://redirect.github.com/github/codeql-action/pull/3794">#3794</a></li> <li>Fixed a bug in the validation of OIDC configurations for private registries that was added in CodeQL Action 4.33.0 / 3.33.0. <a href="https://redirect.github.com/github/codeql-action/pull/3807">#3807</a></li> <li>Update default CodeQL bundle version to <a href="https://github.com/github/codeql-action/releases/tag/codeql-bundle-v2.25.2">2.25.2</a>. <a href="https://redirect.github.com/github/codeql-action/pull/3823">#3823</a></li> </ul> </blockquote> </details> <details> <summary>Changelog</summary> <p><em>Sourced from <a href="https://github.com/github/codeql-action/blob/main/CHANGELOG.md">github/codeql-action's changelog</a>.</em></p> <blockquote> <h1>CodeQL Action Changelog</h1> <p>See the <a href="https://github.com/github/codeql-action/releases">releases page</a> for the relevant changes to the CodeQL CLI and language packs.</p> <h2>[UNRELEASED]</h2> <p>No user facing changes.</p> <h2>4.35.3 - 01 May 2026</h2> <ul> <li><em>Upcoming breaking change</em>: Add a deprecation warning for customers using CodeQL version 2.19.3 and earlier. These versions of CodeQL were discontinued on 9 April 2026 alongside GitHub Enterprise Server 3.15, and will be unsupported by the next minor release of the CodeQL Action. <a href="https://redirect.github.com/github/codeql-action/pull/3837">#3837</a></li> <li>Configurations for private registries that use Cloudsmith or GCP OIDC are now accepted. <a href="https://redirect.github.com/github/codeql-action/pull/3850">#3850</a></li> <li>Best-effort connection tests for private registries now use <code>GET</code> requests instead of <code>HEAD</code> for better compatibility with various registry implementations. For NuGet feeds, the test is now always performed against the service index. <a href="https://redirect.github.com/github/codeql-action/pull/3853">#3853</a></li> <li>Fixed a bug where two diagnostics produced within the same millisecond could overwrite each other on disk, causing one of them to be lost. <a href="https://redirect.github.com/github/codeql-action/pull/3852">#3852</a></li> <li>Update default CodeQL bundle version to <a href="https://github.com/github/codeql-action/releases/tag/codeql-bundle-v2.25.3">2.25.3</a>. <a href="https://redirect.github.com/github/codeql-action/pull/3865">#3865</a></li> </ul> <h2>4.35.2 - 15 Apr 2026</h2> <ul> <li>The undocumented TRAP cache cleanup feature that could be enabled using the <code>CODEQL_ACTION_CLEANUP_TRAP_CACHES</code> environment variable is deprecated and will be removed in May 2026. If you are affected by this, we recommend disabling TRAP caching by passing the <code>trap-caching: false</code> input to the <code>init</code> Action. <a href="https://redirect.github.com/github/codeql-action/pull/3795">#3795</a></li> <li>The Git version 2.36.0 requirement for improved incremental analysis now only applies to repositories that contain submodules. <a href="https://redirect.github.com/github/codeql-action/pull/3789">#3789</a></li> <li>Python analysis on GHES no longer extracts the standard library, relying instead on models of the standard library. This should result in significantly faster extraction and analysis times, while the effect on alerts should be minimal. <a href="https://redirect.github.com/github/codeql-action/pull/3794">#3794</a></li> <li>Fixed a bug in the validation of OIDC configurations for private registries that was added in CodeQL Action 4.33.0 / 3.33.0. <a href="https://redirect.github.com/github/codeql-action/pull/3807">#3807</a></li> <li>Update default CodeQL bundle version to <a href="https://github.com/github/codeql-action/releases/tag/codeql-bundle-v2.25.2">2.25.2</a>. <a href="https://redirect.github.com/github/codeql-action/pull/3823">#3823</a></li> </ul> <h2>4.35.1 - 27 Mar 2026</h2> <ul> <li>Fix incorrect minimum required Git version for <a href="https://redirect.github.com/github/roadmap/issues/1158">improved incremental analysis</a>: it should have been 2.36.0, not 2.11.0. <a href="https://redirect.github.com/github/codeql-action/pull/3781">#3781</a></li> </ul> <h2>4.35.0 - 27 Mar 2026</h2> <ul> <li>Reduced the minimum Git version required for <a href="https://redirect.github.com/github/roadmap/issues/1158">improved incremental analysis</a> from 2.38.0 to 2.11.0. <a href="https://redirect.github.com/github/codeql-action/pull/3767">#3767</a></li> <li>Update default CodeQL bundle version to <a href="https://github.com/github/codeql-action/releases/tag/codeql-bundle-v2.25.1">2.25.1</a>. <a href="https://redirect.github.com/github/codeql-action/pull/3773">#3773</a></li> </ul> <h2>4.34.1 - 20 Mar 2026</h2> <ul> <li>Downgrade default CodeQL bundle version to <a href="https://github.com/github/codeql-action/releases/tag/codeql-bundle-v2.24.3">2.24.3</a> due to issues with a small percentage of Actions and JavaScript analyses. <a href="https://redirect.github.com/github/codeql-action/pull/3762">#3762</a></li> </ul> <h2>4.34.0 - 20 Mar 2026</h2> <ul> <li>Added an experimental change which disables TRAP caching when <a href="https://redirect.github.com/github/roadmap/issues/1158">improved incremental analysis</a> is enabled, since improved incremental analysis supersedes TRAP caching. This will improve performance and reduce Actions cache usage. We expect to roll this change out to everyone in March. <a href="https://redirect.github.com/github/codeql-action/pull/3569">#3569</a></li> <li>We are rolling out improved incremental analysis to C/C++ analyses that use build mode <code>none</code>. We expect this rollout to be complete by the end of April 2026. <a href="https://redirect.github.com/github/codeql-action/pull/3584">#3584</a></li> <li>Update default CodeQL bundle version to <a href="https://github.com/github/codeql-action/releases/tag/codeql-bundle-v2.25.0">2.25.0</a>. <a href="https://redirect.github.com/github/codeql-action/pull/3585">#3585</a></li> </ul> <h2>4.33.0 - 16 Mar 2026</h2> <ul> <li> <p>Upcoming change: Starting April 2026, the CodeQL Action will skip collecting file coverage information on pull requests to improve analysis performance. File coverage information will still be computed on non-PR analyses. Pull request analyses will log a warning about this upcoming change. <a href="https://redirect.github.com/github/codeql-action/pull/3562">#3562</a></p> <p>To opt out of this change:</p> <ul> <li><strong>Repositories owned by an organization:</strong> Create a custom repository property with the name <code>github-codeql-file-coverage-on-prs</code> and the type "True/false", then set this property to <code>true</code> in the repository's settings. For more information, see <a href="https://docs.github.com/en/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization">Managing custom properties for repositories in your organization</a>. Alternatively, if you are using an advanced setup workflow, you can set the <code>CODEQL_ACTION_FILE_COVERAGE_ON_PRS</code> environment variable to <code>true</code> in your workflow.</li> <li><strong>User-owned repositories using default setup:</strong> Switch to an advanced setup workflow and set the <code>CODEQL_ACTION_FILE_COVERAGE_ON_PRS</code> environment variable to <code>true</code> in your workflow.</li> </ul> </li> </ul> </blockquote> <p>... (truncated)</p> </details> <details> <summary>Commits</summary> <ul> <li><a href="https://github.com/github/codeql-action/commit/e46ed2cbd01164d986452f91f178727624ae40d7"><code>e46ed2c</code></a> Merge pull request <a href="https://redirect.github.com/github/codeql-action/issues/3867">#3867</a> from github/update-v4.35.3-8c6e48dbe</li> <li><a href="https://github.com/github/codeql-action/commit/b73d1d163446ca5e62b96698027210ab41df6a4a"><code>b73d1d1</code></a> Add changelog entry for <a href="https://redirect.github.com/github/codeql-action/issues/3853">#3853</a></li> <li><a href="https://github.com/github/codeql-action/commit/24e0bb00a931e2a5edb703ce3b22a70f3a3e800b"><code>24e0bb0</code></a> Reorder changelog entries</li> <li><a href="https://github.com/github/codeql-action/commit/ec298daba71cf7592feacbd1c0887cddc0659f62"><code>ec298da</code></a> Update changelog for v4.35.3</li> <li><a href="https://github.com/github/codeql-action/commit/8c6e48dbe051ceb3015c19554831af1b43275f46"><code>8c6e48d</code></a> Merge pull request <a href="https://redirect.github.com/github/codeql-action/issues/3865">#3865</a> from github/update-bundle/codeql-bundle-v2.25.3</li> <li><a href="https://github.com/github/codeql-action/commit/719098349ea5beae8aa364bf9b71ff1c8d937df2"><code>7190983</code></a> Add changelog note</li> <li><a href="https://github.com/github/codeql-action/commit/2bb209555a024d051f6271c8a846b402497f9445"><code>2bb2095</code></a> Update default bundle to codeql-bundle-v2.25.3</li> <li><a href="https://github.com/github/codeql-action/commit/7851e55dc3be31ec4bcc3ef98453de2cb306e698"><code>7851e55</code></a> Merge pull request <a href="https://redirect.github.com/github/codeql-action/issues/3850">#3850</a> from github/mbg/private-registry/cloudsmith-gcp</li> <li><a href="https://github.com/github/codeql-action/commit/262a15f6cf4c7a43d6a38ad76392e5e2d4977751"><code>262a15f</code></a> Add generic non-printable chars test for OIDC configs</li> <li><a href="https://github.com/github/codeql-action/commit/a6109b1c07173a53ece3d179a925ff9644d1fabd"><code>a6109b1</code></a> Merge pull request <a href="https://redirect.github.com/github/codeql-action/issues/3853">#3853</a> from github/mbg/start-proxy/improved-checks</li> <li>Additional commits viewable in <a href="https://github.com/github/codeql-action/compare/c10b8064de6f491fea524254123dbe5e09572f13...e46ed2cbd01164d986452f91f178727624ae40d7">compare view</a></li> </ul> </details> <br /> Updates `actions/cache` from 5.0.4 to 5.0.5 <details> <summary>Release notes</summary> <p><em>Sourced from <a href="https://github.com/actions/cache/releases">actions/cache's releases</a>.</em></p> <blockquote> <h2>v5.0.5</h2> <h2>What's Changed</h2> <ul> <li>Update ts-http-runtime dependency by <a href="https://github.com/yacaovsnc"><code>@yacaovsnc</code></a> in <a href="https://redirect.github.com/actions/cache/pull/1747">actions/cache#1747</a></li> </ul> <p><strong>Full Changelog</strong>: <a href="https://github.com/actions/cache/compare/v5...v5.0.5">https://github.com/actions/cache/compare/v5...v5.0.5</a></p> </blockquote> </details> <details> <summary>Changelog</summary> <p><em>Sourced from <a href="https://github.com/actions/cache/blob/main/RELEASES.md">actions/cache's changelog</a>.</em></p> <blockquote> <h1>Releases</h1> <h2>How to prepare a release</h2> <blockquote> <p>[!NOTE]<br /> Relevant for maintainers with write access only.</p> </blockquote> <ol> <li>Switch to a new branch from <code>main</code>.</li> <li>Run <code>npm test</code> to ensure all tests are passing.</li> <li>Update the version in <a href="https://github.com/actions/cache/blob/main/package.json"><code>https://github.com/actions/cache/blob/main/package.json</code></a>.</li> <li>Run <code>npm run build</code> to update the compiled files.</li> <li>Update this <a href="https://github.com/actions/cache/blob/main/RELEASES.md"><code>https://github.com/actions/cache/blob/main/RELEASES.md</code></a> with the new version and changes in the <code>## Changelog</code> section.</li> <li>Run <code>licensed cache</code> to update the license report.</li> <li>Run <code>licensed status</code> and resolve any warnings by updating the <a href="https://github.com/actions/cache/blob/main/.licensed.yml"><code>https://github.com/actions/cache/blob/main/.licensed.yml</code></a> file with the exceptions.</li> <li>Commit your changes and push your branch upstream.</li> <li>Open a pull request against <code>main</code> and get it reviewed and merged.</li> <li>Draft a new release <a href="https://github.com/actions/cache/releases">https://github.com/actions/cache/releases</a> use the same version number used in <code>package.json</code> <ol> <li>Create a new tag with the version number.</li> <li>Auto generate release notes and update them to match the changes you made in <code>RELEASES.md</code>.</li> <li>Toggle the set as the latest release option.</li> <li>Publish the release.</li> </ol> </li> <li>Navigate to <a href="https://github.com/actions/cache/actions/workflows/release-new-action-version.yml">https://github.com/actions/cache/actions/workflows/release-new-action-version.yml</a> <ol> <li>There should be a workflow run queued with the same version number.</li> <li>Approve the run to publish the new version and update the major tags for this action.</li> </ol> </li> </ol> <h2>Changelog</h2> <h3>5.0.4</h3> <ul> <li>Bump <code>minimatch</code> to v3.1.5 (fixes ReDoS via globstar patterns)</li> <li>Bump <code>undici</code> to v6.24.1 (WebSocket decompression bomb protection, header validation fixes)</li> <li>Bump <code>fast-xml-parser</code> to v5.5.6</li> </ul> <h3>5.0.3</h3> <ul> <li>Bump <code>@actions/cache</code> to v5.0.5 (Resolves: <a href="https://github.com/actions/cache/security/dependabot/33">https://github.com/actions/cache/security/dependabot/33</a>)</li> <li>Bump <code>@actions/core</code> to v2.0.3</li> </ul> <h3>5.0.2</h3> <ul> <li>Bump <code>@actions/cache</code> to v5.0.3 <a href="https://redirect.github.com/actions/cache/pull/1692">#1692</a></li> </ul> <h3>5.0.1</h3> <ul> <li>Update <code>@azure/storage-blob</code> to <code>^12.29.1</code> via <code>@actions/cache@5.0.1</code> <a href="https://redirect.github.com/actions/cache/pull/1685">#1685</a></li> </ul> <h3>5.0.0</h3> <blockquote> <p>[!IMPORTANT] <code>actions/cache@v5</code> runs on the Node.js 24 runtime and requires a minimum Actions Runner version of <code>2.327.1</code>.</p> </blockquote> </blockquote> <p>... (truncated)</p> </details> <details> <summary>Commits</summary> <ul> <li><a href="https://github.com/actions/cache/commit/27d5ce7f107fe9357f9df03efb73ab90386fccae"><code>27d5ce7</code></a> Merge pull request <a href="https://redirect.github.com/actions/cache/issues/1747">#1747</a> from actions/yacaovsnc/update-dependency</li> <li><a href="https://github.com/actions/cache/commit/f280785d7b6e1884c7d12b9136eb0f4a1574fcfd"><code>f280785</code></a> licensed changes</li> <li><a href="https://github.com/actions/cache/commit/619aeb1606e195be0b36fd0ff68dcf1aff6b65a7"><code>619aeb1</code></a> npm run build generated dist files</li> <li><a href="https://github.com/actions/cache/commit/bcf16c2893940a4899761e55c7ac3c1cf88a04f6"><code>bcf16c2</code></a> Update ts-http-runtime to 0.3.5</li> <li>See full diff in <a href="https://github.com/actions/cache/compare/668228422ae6a00e4ad889ee87cd7109ec5666a7...27d5ce7f107fe9357f9df03efb73ab90386fccae">compare view</a></li> </ul> </details> <br /> Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting `@dependabot rebase`. --- <details> <summary>Dependabot commands and options</summary> <br /> You can trigger Dependabot actions by commenting on this PR: - `@dependabot rebase` will rebase this PR - `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it - `@dependabot show <dependency name> ignore conditions` will show all of the ignore conditions of the specified dependency - `@dependabot ignore <dependency name> major version` will close this group update PR and stop Dependabot creating any more for the specific dependency's major version (unless you unignore this specific dependency's major version or upgrade to it yourself) - `@dependabot ignore <dependency name> minor version` will close this group update PR and stop Dependabot creating any more for the specific dependency's minor version (unless you unignore this specific dependency's minor version or upgrade to it yourself) - `@dependabot ignore <dependency name>` will close this group update PR and stop Dependabot creating any more for the specific dependency (unless you unignore this specific dependency or upgrade to it yourself) - `@dependabot unignore <dependency name>` will remove all of the ignore conditions of the specified dependency - `@dependabot unignore <dependency name> <ignore condition>` will remove the ignore condition of the specified dependency and ignore conditions </details>
Use dart doc to generate HTML documentation for your Dart package.
For information about contributing to the dartdoc project, see the contributor docs.
For issues/details related to the hosted Dart SDK API docs, see dart-lang/api.dart.dev.
The dart tool, with the dart doc command, is part of the Dart SDK.
Run dart doc . from the root directory of a package. You must first run dart pub get or flutter pub get and your package must analyze without errors with dart analyze or flutter analyze as appropriate. Here is an example of dartdoc documenting itself:
$ dart pub get ... $ dart doc . Documenting dartdoc... ... Initialized dartdoc with 766 libraries in 63.9 seconds Generating docs for library dartdoc from package:dartdoc/dartdoc.dart... Validating docs... no issues found 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.
To view the generated documentation, you must load them with an HTTP server. To learn more, follow the Viewing docs guide.
Run dart help doc to see the available command-line options.
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 package:dhttpd. For example:
$ dart pub global activate dhttpd $ dart pub global run dhttpd --path doc/api
To then read the generated docs in your browser, open the link that dhttpd outputs, usually http://localhost:8080.
dartdoc produces static files with a predictable link structure.
index.html # homepage
index.json # machine-readable index
library-name/ # : is turned into a - e.g. dart:core => dart-core
ClassName-class.html # "homepage" for a class (and enum)
ClassName/
ClassName.html # constructor
ClassName.namedConstructor.html # named constructor
method.html
property.html
CONSTANT.html
property.html
top-level-function.html
File names are case-sensitive.
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 dart doc.
dart doc will not generate documentation for a Dart element and its children that have the @nodoc tag in the documentation comment.
Creating a file named dartdoc_options.yaml at the top of your package can change how Dartdoc generates docs.
An example (not necessarily recommended settings):
dartdoc: categories: awesome: markdown: doc/First.md displayName: Awesome great: markdown: doc/Second.md displayName: Great categoryOrder: [awesome, great] includeExternal: ['bin/unusually_located_library.dart'] nodoc: ['lib/sekret/*.dart'] linkTo: url: "https://my.dartdocumentationsite.org/dev/%v%" showUndocumentedCategories: true ignore: - ambiguous-doc-reference errors: - unresolved-doc-reference warnings: - tool-error
dartdoc_options.yaml fieldsIn general, paths are relative to the directory of the dartdoc_options.yaml file in which the option is defined, and should be specified as POSIX paths. Dartdoc will convert POSIX paths automatically on Windows. Unrecognized options will be ignored. Supported options:
markdown: property and an optional displayName: property. For topics you'd like to document, specify a markdown file to be rendered on the category page, using the markdown: property. Optionally, you may specify a displayName: to be used in the rendered HTML, instead of the category name. Categories are referenced in documentation comments using the {@category <category name>} tag. Categories with no matching category name defined in dartdoc_options.yaml will be invisible.--exclude. See also nodoc.--errors, --warnings, and --ignore.--errors, --warnings, and --ignore.--include).url: A string indicating the base URL for documentation of this package. Ordinarily you do not need to set this in the package: consider --link-to-hosted and --link-to-sdks instead of this option if you need to build your own website with dartdoc.
The following strings will be substituted in to complete the URL:
%b%: The branch as indicated by text in the version. 2.0.0-dev.3 is branch “dev”. No branch is considered to be “stable”.%n%: The name of this package, as defined in pubspec.yaml.%v%: The version of this package as defined in pubspec.yaml.excludes: A list of directories to exclude from processing source links.
root: The directory to consider the ‘root’ for inserting relative paths into the template. Source code outside the root directory will not be linked.
uriTemplate: A template to substitute revision and file path information. If revision is present in the template but not specified, or if root is not specified, dartdoc will throw an exception. To hard-code a revision, don't specify it with %r%.
The following strings will be substituted in to complete the URL:
%f%: Relative path of file to the repository root%r%: Revision%l%: Line number@nodoc tag in the documentation comment of every defined element. Unlike exclude this can specify source files directly, and neither inheritance nor reexports will cause these elements to be documented when included in other libraries. For more fine-grained control, use @nodoc in element documentation comments directly, or the exclude directive.--errors, --warnings, and --ignore.Unsupported and experimental options:
You can tag libraries or top level classes, functions, and variables in their documentation with the string {@category YourCategory}. For libraries, that will cause the library to appear in a category when showing the sidebar on the Package and Library pages. For other types of objects, the {@category} will be shown with a link to the category page but only if specified in dartdoc_options.yaml, as above.
/// Here is my library. /// /// {@category awesome} library my_library;
A file categories.json will be generated at the top level of the documentation tree with information about categories collected from objects in the source tree. The directives @category, and @subCategory are understood and saved into this json.
As an example, if we document the class Icon in flutter using the following:
/// {@category Basics} /// {@category Assets and Icons} /// {@subCategory Information displays} class Icon extends StatelessWidget {}
that will result in the following json:
{ "name": "Icon", "qualifiedName": "widgets.Icon", "href": "widgets/Icon-class.html", "type": "class", "categories": [ "Assets and Icons", "Basics" ], "subcategories": [ "Information displays" ], }
You can specify links to videos inline that will be handled with a simple HTML5 player:
/// This widget is a dancing Linux penguin. /// /// {@animation name 100 200 http://host.com/path/to/video.mp4}
‘name’ is user defined, and the numbers are the width and height of the animation in pixels.
You can specify “macros”, i.e. reusable pieces of documentation. For that, first specify a template anywhere in the comments, like:
/// {@template template_name} /// Some shared docs /// {@endtemplate}
and then you can insert it via {@macro template_name}, like
/// Some comment /// {@macro template_name} /// More comments
Template definitions are currently unscoped -- if dartdoc reads a file containing a template, it can be used in anything dartdoc is currently documenting. This can lead to inconsistent behavior between runs on different packages, especially if different command lines are used for dartdoc. It is recommended to use collision-resistant naming for any macros by including the package name and/or library it is defined in within the name.
Dartdoc allows you to filter parts of the documentation through an external tool and then include the output of that tool in place of the given input.
First, you have to configure the tools that will be used in the dartdoc_options.yaml file:
dartdoc: tools: drill: command: ["bin/drill.dart"] setup_command: ["bin/setup.dart"] description: "Puts holes in things." compile_args: ["--no-sound-null-safety"] echo: macos: ['/bin/sh', '-c', 'echo'] setup_macos: ['/bin/sh', '-c', 'setup.sh'] linux: ['/bin/sh', '-c', 'echo'] setup_linux: ['/bin/sh', '-c', 'setup.sh'] windows: ['C:\\Windows\\System32\\cmd.exe', '/c', 'echo'] setup_windows: ['/bin/sh', '-c', 'setup.sh'] description: 'Works on everything'
The command tag is used to describe the command executable, and any options that are common among all executions. If the first element of this list is a filename that ends in .dart, then the dart executable will automatically be used to invoke that script. The command defined will be run on all platforms.
If the command is a Dart script, then the first time it is run, a snapshot will be created using the input and first-time arguments as training arguments, and will be run from the snapshot from then on. Note that the Platform.script property will point to the snapshot location during the snapshot runs. You can obtain the original .dart script location in a tool by looking at the TOOL_COMMAND environment variable.
The setup_command tag is used to describe a command executable, and any options, for a command that is run once before running a tool for the first time. If the first element of this list is a filename that ends in .dart, then the dart executable will automatically be used to invoke that script. The setup_command defined will be run on all platforms. If the setup command is a Dart script, then it will be run with the Dart executable, but will not be snapshotted, as it will only be run once.
The macos, linux, and windows tags are used to describe the commands to be run on each of those platforms, and the setup_macos, setup_linux, and setup_windows tags define setup commands for their respective platforms.
The description is just a short description of the tool for use as help text.
Only tools which are configured in the dartdoc_options.yaml file are able to be invoked.
The compile_args tag is used to pass options to the dart compiler when the first run of the tool is being snapshotted.
To use the tools in comment documentation, use the {@tool <name> [<options> ...] [$INPUT]} directive to invoke the tool:
/// {@tool drill --flag --option="value" $INPUT} /// This is the text that will be sent to the tool as input. /// {@end-tool}
The $INPUT argument is a special token that will be replaced with the name of a temporary file that the tool needs to read from. It can appear anywhere in the options, and can appear multiple times.
If the example drill tool with those options is a tool that turns the content of its input file into a code-font heading, then the directive above would be the equivalent of having the following comment in the code:
/// # `This is the text that will be sent to the tool as input.`
Tools have a number of environment variables available to them. They will be interpolated into any arguments given to the tool as $ENV_VAR or $(ENV_VAR), as well as available in the process environment.
SOURCE_LINE: The source line number in the original source code.SOURCE_COLUMN: The source column in the original source code.SOURCE_PATH: The relative path from the package root to the original source file.PACKAGE_PATH: The path to the package root.PACKAGE_NAME: The name of the package.LIBRARY_NAME: The name of the library, if any.ELEMENT_NAME: The name of the element that this doc is attached to.TOOL_COMMAND: The path to the original .dart script or command executable.DART_SNAPSHOT_CACHE: The path to the directory containing the snapshot files of the tools. This directory will be removed before Dartdoc exits.DART_SETUP_COMMAND: The path to the setup command script, if any.INVOCATION_INDEX: An index for how many times a tool directive has been invoked on the current dartdoc block. Allows multiple tool invocations on the same block to be differentiated.It rarely happens, but sometimes what you really need is to inject some raw HTML into the dartdoc output, without it being subject to Markdown processing beforehand. This can be useful when the output of an external tool is HTML, for instance. This is where the {@inject-html}...{@end-inject-html} tags come in.
For security reasons, the {@inject-html} directive will be ignored unless the --inject-html flag is given on the dartdoc command line.
Since this HTML fragment doesn‘t undergo Markdown processing, reference links and other normal processing won’t happen on the contained fragment.
So, this:
/// {@inject-html} /// <p>[The HTML to inject.]()</p> /// {@end-inject-html}
Will result in this be emitted in its place in the HTML output (notice that the markdown link isn't linked).
<p>[The HTML to inject.]()</p>
It‘s best to only inject HTML that is self-contained and doesn’t depend upon other elements on the page, since those may change in future versions of Dartdoc.
If --auto-include-dependencies flag is provided, dartdoc tries to automatically add all the used libraries, even from other packages, to the list of the documented libraries.
The source linking feature in dartdoc is a little tricky to use, since pub packages do not actually include enough information to link back to source code and that‘s the context in which documentation is generated for the pub site. This means that for now, it must be manually specified in dartdoc_options.yaml what revision to use. It is currently a recommended practice to specify a revision in dartdoc_options.yaml that points to the same revision as your public package. If you’re using a documentation staging system outside of Dart's pub site, override the template and revision on the command line with the head revision number. You can use the branch name, but generated docs will generate locations that may start drifting with further changes to the branch.
Example dartdoc_options.yaml:
linkToSource: root: '.' uriTemplate: 'https://github.com/dart-lang/dartdoc/blob/v0.28.0/%f%#L%l%'
Example staging command line:
dart pub global run dartdoc --link-to-source-root '.' --link-to-source-revision 6fac6f770d271312c88e8ae881861702a9a605be --link-to-source-uri-template 'https://github.com/dart-lang/dartdoc/blob/%r%/%f%#L%l%'
This gets more complicated with --auto-include-dependencies as these command line flags will override all settings from individual packages. In that case, to preserve source links from third party packages it may be necessary to generate dartdoc_options.yaml options for each package you are intending to add source links to yourself.
Dartdoc supports enabling experimental Dart language features. These can be specified in three ways, in order of precedence:
--enable-experiment flag.dart doc --enable-experiment=macros
dartdoc_options.yaml: Add them under the dartdoc key.dartdoc: enable-experiment: - macros
analysis_options.yaml: Dartdoc automatically respects experiments defined in your project's standard analysis configuration.analyzer: enable-experiment: - macros
Note that specifying experiments via CLI or dartdoc_options.yaml will completely override any experiments defined in analysis_options.yaml.
Please file reports on the GitHub Issue Tracker. Issues are labeled with priority based on how much impact to the ecosystem the issue addresses and the number of generated pages that show the anomaly (widespread vs. not widespread).
Some examples of likely triage priorities:
P0
P1
P2
P3
Please see the dartdoc license.
Generated docs include:
github.css (c) Vasily Polovnyov vast@whiteants.net