馃 chore: sync skills directory from dart-lang/skills - #227
馃 chore: sync skills directory from dart-lang/skills#227flutter-skills-sync-bot wants to merge 1 commit into
Conversation
There was a problem hiding this comment.
Code Review
This pull request updates the version of the dart-flutter plugin to 1.0.3, updates the skills githash, and introduces a new skill guide (SKILL.md) explaining how to use external code examples in Dartdoc with the {@example} directive. The review feedback focuses on improving the newly added documentation by ensuring consistent placeholder formatting, refining phrasing for clarity, eliminating repetitive words, and standardizing the capitalization of "Dartdoc".
| ## 1. The `{@example}` Directive | ||
| The `{@example}` directive parses an external file and resolves it into a fenced Markdown code block in the generated documentation. | ||
|
|
||
| **Syntax:** `{@example <path>[#<region>] [lang=LANGUAGE] [indent=keep|strip]}` |
There was a problem hiding this comment.
For consistency with <path> and <region>, the placeholder for the language should also use angle brackets (e.g., <language>).
| **Syntax:** `{@example <path>[#<region>] [lang=LANGUAGE] [indent=keep|strip]}` | |
| **Syntax:** `{@example <path>[#<region>] [lang=<language>] [indent=keep|strip]}` |
|
|
||
| **Syntax:** `{@example <path>[#<region>] [lang=LANGUAGE] [indent=keep|strip]}` | ||
|
|
||
| * **`<path>`**: The path to the file. A leading `/` evaluates from the package root. Otherwise, it is relative to the current file. |
There was a problem hiding this comment.
The phrase 'evaluates from the package root' is slightly awkward. It is clearer to say 'resolves from the package root' or 'is evaluated relative to the package root'.
| * **`<path>`**: The path to the file. A leading `/` evaluates from the package root. Otherwise, it is relative to the current file. | |
| * **`<path>`**: The path to the file. A leading `/` resolves from the package root. Otherwise, it is relative to the current file. |
| * **Boundary Enforcement:** Using `..` segments to traverse upward is perfectly acceptable, but dartdoc natively stops directory traversal at the package root (it will never escape the package). | ||
| * **No Network URLs:** Absolute URIs (e.g., starting with `https://`) are strictly not supported. The example file *must* sit natively somewhere in the local filesystem. | ||
| * **Separators & Encoding:** Because dartdoc resolves the path as a URI, you must always use forward slashes (`/`) as folder separators (even on Windows). You can natively include URI-encoded characters (like `%20` for spaces) as permitted by URI reference rules. |
There was a problem hiding this comment.
The word 'natively' is used repetitively across these three consecutive points (lines 89, 90, and 91). Additionally, 'Dartdoc' is capitalized inconsistently (lowercase 'dartdoc' is used here, while capitalized 'Dartdoc' is used elsewhere in the document). Let's rephrase these points to improve readability, eliminate the repetition, and ensure consistent capitalization.
| * **Boundary Enforcement:** Using `..` segments to traverse upward is perfectly acceptable, but dartdoc natively stops directory traversal at the package root (it will never escape the package). | |
| * **No Network URLs:** Absolute URIs (e.g., starting with `https://`) are strictly not supported. The example file *must* sit natively somewhere in the local filesystem. | |
| * **Separators & Encoding:** Because dartdoc resolves the path as a URI, you must always use forward slashes (`/`) as folder separators (even on Windows). You can natively include URI-encoded characters (like `%20` for spaces) as permitted by URI reference rules. | |
| * **Boundary Enforcement:** Using `..` segments to traverse upward is perfectly acceptable, but Dartdoc stops directory traversal at the package root (it will never escape the package). | |
| * **No Network URLs:** Absolute URIs (e.g., starting with `https://`) are strictly not supported. The example file *must* reside somewhere in the local filesystem. | |
| * **Separators & Encoding:** Because Dartdoc resolves the path as a URI, you must always use forward slashes (`/`) as folder separators (even on Windows). You can include URI-encoded characters (like `%20` for spaces) as permitted by URI reference rules. |
Automated changes by create-pull-request GitHub action