Add a hideConstantImplementations dartdoc directive #3398
Conversation
| ```dart | ||
| /// This is truly an amazing library. | ||
| /// {@hideConstantImplementations} | ||
| library my_library; |
There was a problem hiding this comment.
nit: I think we're steering away from named libraries like this; we can use library; in Dart 2.19.
|
|
||
| final _canonicalRegExp = RegExp(r'{@canonicalFor\s([^}]+)}'); | ||
|
|
||
| /// Used by [Library] to implement the canonicalFor directive. |
There was a problem hiding this comment.
Can we wrap 'canonicalFor' in some delimiter like backticks?
| /// Mixin implementing dartdoc categorization for ModelElements. | ||
| mixin Categorization implements ModelElement { | ||
| /// Mixin parsing the `@category` directive for ModelElements. | ||
| mixin Categorization on DocumentationComment implements Indexable { |
|
|
||
| /// [true] if the {@hideConstantImplementations} dartdoc directive is present | ||
| /// in the documentation for this class. | ||
| bool get hideConstantImplementations { |
There was a problem hiding this comment.
The name here makes it sound like a function, like calling hideConstantImplementations will do something or set something. What about hasHideConstantImplementations, like how the analyzer APIs are named?
| return _hideConstantImplementations!; | ||
| } | ||
|
|
||
| /// Hides [hideConstantImplementations] from doc while leaving a note to |
There was a problem hiding this comment.
Hmm, is this reference right? This function doesn't hide the bool getter, hideConstantImplementations. Maybe "Hides {@hideConstantImplementations} ..."?
| @@ -266,6 +267,10 @@ mixin GetterSetterCombo on ModelElement { | |||
|
|
|||
| bool get writeOnly => hasPublicSetter && !hasPublicGetter; | |||
|
|
|||
| /// True if the @hideConstantImplementations directive is present | |||
| /// in the defining enclosing element. | |||
| bool get hideConstantImplementation; | |||
There was a problem hiding this comment.
Same naming for here, maybe hasHide... or shouldHide...?
|
The grind.dart changes are due to some yaks that needed shaving: the name |
…c pages (#128442) This updates dartdoc to 6.3.0. Release notes are available, here: https://github.com/dart-lang/dartdoc/releases/tag/v6.3.0 Most important for Flutter are the reduction in the size of generated HTML files (dart-lang/dartdoc#3384) and a new dartdoc directive to hide constant implementations from indicated classes (dart-lang/dartdoc#3398), which fixes the longstanding issue (dart-lang/dartdoc#2657). I've also added the api documentation zip to `.gitignore` and the `{@hideConstantImplementations}` dartdoc directive to the motivating example. A screenshot:  I assert that this change to icons.dart should be test-exempt as existing tests cover whether or not dartdoc directives are recognized or are leaking into HTML, and the impact of adding the directive was tested in dart-lang/dartdoc#3398.
Directive introduced in dart-lang/dartdoc#3398 but not documented yet. Still experimental, but used by Flutter. Change-Id: I277927a54caf926b0b3d13db589486465ab9358d Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/328180 Commit-Queue: Samuel Rawlins <[email protected]> Reviewed-by: Phil Quitslund <[email protected]>
Fixes #2657.
Without trying to solve #3397 this PR does also move a few things around to make it more clear where the various directives are currently implemented as adding yet another one via
buildDocumentationAdditionwas starting to look messy.Here is a sample screenshot of what
Iconswould look like with the new directive: