analyzer: recognize example doc directive

[Musharaf-khan]

Fixes #63504.

This PR updates the analyzer doc comment parser to recognize the dartdoc {@example ...} directive.

Changes:

• Adds example to DocDirectiveType
• Parses {@example ...} as a known simple doc directive
• Adds parser coverage for an example directive using a package-root-relative path

Validation:

• dart test test/src/dart/parser/doc_comment_test.dart -p vm --plain-name 'DocCommentParserTest test_exampleDirective'
• dart test test/src/dart/parser/doc_comment_test.dart

[copybara-service]

Thank you for your contribution! This project uses Gerrit for code reviews. Your pull request has automatically been converted into a code review at:

https://dart-review.googlesource.com/c/sdk/+/516421

Please wait for a developer to review your code review at the above link; you can speed up the review if you sign into Gerrit and manually add a reviewer that has recently worked on the relevant code. See CONTRIBUTING.md to learn how to upload changes to Gerrit directly.

Additional commits pushed to this PR will update both the PR and the corresponding Gerrit CL. After the review is complete on the CL, your reviewer will merge the CL (automatically closing this PR).

[copybara-service]

Gerrit CL has been approved, please wait for a reviewer to merge it.

There are also new comments on the CL, please review them and respond if necessary because reviewer might have requested clarifications or possibly some final changes and will not merge the CL until their questions have been answered.

[copybara-service]

https://dart-review.googlesource.com/c/sdk/+/516421 has been updated with the latest commits from this pull request.

[copybara-service]

https://dart-review.googlesource.com/c/sdk/+/516421 has been updated with the latest commits from this pull request.

[copybara-service]

CL has new comments, please view and respond to them in Gerrit.

If a reviewer requested changes, push new commits to this PR and it will be automatically copied to Gerrit. After that you can mark reviewer comments as resolved in Gerrit and request another round of reviews.

Note: when you add comments in Gerrit they only become visible after you send them by clicking Reply and Send.

[copybara-service]

Gerrit CL has been approved, please wait for a reviewer to merge it.

There are also new comments on the CL, please review them and respond if necessary because reviewer might have requested clarifications or possibly some final changes and will not merge the CL until their questions have been answered.

[copybara-service]

Gerrit CL has been approved, please wait for a reviewer to merge it.

There are also new comments on the CL, please review them and respond if necessary because reviewer might have requested clarifications or possibly some final changes and will not merge the CL until their questions have been answered.

[DanTup]

FYI - some of this work was also done in 7c1ca3f, though it's not as complete as this PR. This PR may need rebasing over it and conflicts resolved.