Skip to content

馃 chore: sync skills directory from dart-lang/skills - #227

Open
flutter-skills-sync-bot wants to merge 1 commit into
mainfrom
automation/sync-dart-skills
Open

馃 chore: sync skills directory from dart-lang/skills#227
flutter-skills-sync-bot wants to merge 1 commit into
mainfrom
automation/sync-dart-skills

Conversation

@flutter-skills-sync-bot

Copy link
Copy Markdown
Collaborator

Automated changes by create-pull-request GitHub action

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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]}`

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

medium

For consistency with <path> and <region>, the placeholder for the language should also use angle brackets (e.g., <language>).

Suggested change
**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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

medium

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'.

Suggested change
* **`<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.

Comment on lines +89 to +91
* **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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

medium

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.

Suggested change
* **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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant