Skip to content

Remove the missing-code-block-language warning #4028

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

Remove the missing-code-block-language warning #4028

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 0 additions & 33 deletions lib/src/model/documentation_comment.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,7 +116,6 @@ mixin DocumentationComment
// them unprocessed causes #2272.
docs = _stripHtmlAndAddToIndex(docs);
}
_analyzeCodeBlocks(docs);
return docs;
}

Expand All @@ -132,7 +131,6 @@ mixin DocumentationComment
// would need to be processed by `processCommentDirectives`.
docs = await _evaluateTools(docs);
docs = processCommentDirectives(docs);
_analyzeCodeBlocks(docs);
return docs;
}

Expand Down Expand Up @@ -699,37 +697,6 @@ mixin DocumentationComment
});
}

static final _codeBlockPattern =
RegExp(r'^[ ]{0,3}(`{3,}|~{3,})(.*)$', multiLine: true);

/// Analyze fenced code blocks present in the documentation comment,
/// warning if there is no language specified.
void _analyzeCodeBlocks(String docs) {
if (config.packageWarningOptions
.warningModes[PackageWarning.missingCodeBlockLanguage] ==
PackageWarningMode.ignore) {
return;
}
final results = _codeBlockPattern.allMatches(docs).toList(growable: false);
if (results.isEmpty) {
return;
}
final firstOfPair = <Match>[];
for (var i = 0; i < results.length; i++) {
if (i.isEven && i != results.length - 1) {
firstOfPair.add(results[i]);
}
}
for (var e in firstOfPair) {
final result = e.group(2)!.trim();
if (result.isEmpty) {
warn(PackageWarning.missingCodeBlockLanguage,
message:
'A fenced code block in Markdown should have a language specified');
}
}
}

bool _documentationLocalIsSet = false;

/// Returns the documentation for this element.
Expand Down
26 changes: 11 additions & 15 deletions lib/src/model/package_graph.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -170,15 +170,14 @@ class PackageGraph with CommentReferable, Nameable {
e.canonicalModelElement == null ||
e is Library ||
e.enclosingElement!.isCanonical) {
for (var d in e.documentationFrom
.where((d) => d.hasDocumentationComment)) {
for (var d
in e.documentationFrom.where((d) => d.hasDocumentationComment)) {
if (d.needsPrecache && !precachedElements.contains(d)) {
precachedElements.add(d as ModelElement);
futures.add(d.precacheLocalDocs());
// [TopLevelVariable]s get their documentation from getters and
// setters, so should be precached if either has a template.
if (e is TopLevelVariable &&
!precachedElements.contains(e)) {
if (e is TopLevelVariable && !precachedElements.contains(e)) {
precachedElements.add(e);
futures.add(e.precacheLocalDocs());
}
Expand Down Expand Up @@ -468,8 +467,7 @@ class PackageGraph with CommentReferable, Nameable {
PackageWarning.typeAsHtml ||
PackageWarning.invalidParameter ||
PackageWarning.toolError ||
PackageWarning.deprecated ||
PackageWarning.missingCodeBlockLanguage =>
PackageWarning.deprecated =>
kind.messageFor([message])
};

Expand Down Expand Up @@ -647,7 +645,8 @@ class PackageGraph with CommentReferable, Nameable {
checkAndAddContainer(modelElement, container);
}
} else if (container is Mixin) {
for (var modelElement in container.superclassConstraints.modelElements) {
for (var modelElement
in container.superclassConstraints.modelElements) {
checkAndAddContainer(modelElement, container);
}
}
Expand Down Expand Up @@ -752,8 +751,7 @@ class PackageGraph with CommentReferable, Nameable {
// TODO(keertip): Find a better way to exclude members of extensions
// when libraries are specified using the "--include" flag.
if (library != null && library.isDocumented) {
return getModelFor(e, library,
enclosingContainer: preferredClass);
return getModelFor(e, library, enclosingContainer: preferredClass);
}
}
// TODO(jcollins-g): The data structures should be changed to eliminate
Expand All @@ -778,8 +776,7 @@ class PackageGraph with CommentReferable, Nameable {
var setterElement = setter2 == null
? null
: getModelFor(setter2, library) as Accessor;
canonicalModelElement = getModelForPropertyInducingElement(
e, library,
canonicalModelElement = getModelForPropertyInducingElement(e, library,
getter: getterElement, setter: setterElement);
} else {
canonicalModelElement = getModelFor(e, library);
Expand All @@ -791,8 +788,7 @@ class PackageGraph with CommentReferable, Nameable {
}
}
// Prefer fields and top-level variables.
if (e is PropertyAccessorElement2 &&
canonicalModelElement is Accessor) {
if (e is PropertyAccessorElement2 && canonicalModelElement is Accessor) {
canonicalModelElement = canonicalModelElement.enclosingCombo;
}
return canonicalModelElement;
Expand All @@ -804,8 +800,8 @@ class PackageGraph with CommentReferable, Nameable {
var elem = modelElement.element;
var candidates = <ModelElement>{};
if (lib != null) {
var constructedWithKey = allConstructedModelElements[
ConstructedModelElementsKey(elem, null)];
var constructedWithKey =
allConstructedModelElements[ConstructedModelElementsKey(elem, null)];
if (constructedWithKey != null) {
candidates.add(constructedWithKey);
}
Expand Down
23 changes: 3 additions & 20 deletions lib/src/warnings.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,6 @@ List<DartdocOption<Object?>> createPackageWarningOptions(
/// Something that package warnings can be reported on. Optionally associated
/// with an analyzer [element].
mixin Warnable implements CommentReferable, Documentable, Locatable {

Element2? get element;

void warn(
Expand Down Expand Up @@ -272,20 +271,6 @@ enum PackageWarning implements Comparable<PackageWarning> {
'deprecated',
'deprecated dartdoc usage: {0}',
shortHelp: 'A dartdoc directive has a deprecated format.',
),
// TODO(kallentu): Remove this warning.
missingCodeBlockLanguage(
'missing-code-block-language',
'missing code block language: {0}',
shortHelp: '(Deprecated: Use `missing_code_block_language_in_doc_comment` '
'lint) A fenced code block is missing a specified language.',
longHelp: '(Deprecated: Use `missing_code_block_language_in_doc_comment` '
'lint) To enable proper syntax highlighting of Markdown code blocks, '
'Dartdoc requires code blocks to specify the language used after the '
'initial declaration. As an example, to specify Dart you would open '
'the Markdown code block with ```dart or ~~~dart.',
defaultWarningMode: PackageWarningMode.ignore,
isDeprecated: true,
);

/// The name which can be used at the command line to enable this warning.
Expand Down Expand Up @@ -542,8 +527,7 @@ class PackageWarningCounter {

/// Whether we've already warned for this combination of [e], [kind],
/// and [messageFragment].
bool hasWarning(
Warnable? e, PackageWarning kind, String messageFragment) {
bool hasWarning(Warnable? e, PackageWarning kind, String messageFragment) {
if (e == null) {
return false;
}
Expand All @@ -558,9 +542,8 @@ class PackageWarningCounter {

/// Adds the warning to the counter, and writes out the fullMessage string
/// if configured to do so.
void addWarning(Warnable? e
, PackageWarning kind, String message,
String fullMessage) {
void addWarning(
Warnable? e, PackageWarning kind, String message, String fullMessage) {
assert(!hasWarning(e, kind, message));
// TODO(jcollins-g): Make addWarning not accept nulls for element.
PackageWarningOptionContext config =
Expand Down
66 changes: 0 additions & 66 deletions test/documentation_comment_test.dart
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -763,72 +763,6 @@ Text.
);
}

void test_fencedCodeBlockDoesNotSpecifyLanguage() async {
await writePackageWithCommentedLibrary('''
/// ```
/// void main() {}
/// ```
''');

expect(
packageGraph.packageWarningCounter.hasWarning(
libraryModel,
PackageWarning.missingCodeBlockLanguage,
'A fenced code block in Markdown should have a language specified'),
isTrue,
);
}

void test_squigglyFencedCodeBlockDoesNotSpecifyLanguage() async {
await writePackageWithCommentedLibrary('''
/// ~~~
/// void main() {}
/// ~~~
''');

expect(
packageGraph.packageWarningCounter.hasWarning(
libraryModel,
PackageWarning.missingCodeBlockLanguage,
'A fenced code block in Markdown should have a language specified'),
isTrue,
);
}

void test_fencedCodeBlockDoesSpecifyLanguage() async {
await writePackageWithCommentedLibrary('''
/// ```dart
/// void main() {}
/// ```
''');

expect(
packageGraph.packageWarningCounter.hasWarning(
libraryModel,
PackageWarning.missingCodeBlockLanguage,
'A fenced code block in Markdown should have a language specified'),
isFalse,
);
}

void test_fencedBlockIsNotClosed() async {
await writePackageWithCommentedLibrary('''
/// ```
/// A not closed fenced code block
''');

expect(
packageGraph.packageWarningCounter.hasWarning(
libraryModel,
PackageWarning.missingCodeBlockLanguage,
'A fenced code block in Markdown should have a language specified'),
isFalse,
);
}

Matcher hasDeprecatedWarning(String message) =>
_HasWarning(PackageWarning.deprecated, message);

Matcher hasInvalidParameterWarning(String message) =>
_HasWarning(PackageWarning.invalidParameter, message);

Expand Down