Skip to content

Commit 703e08d

Browse files
parloughparlough
authored
Some minor rendering code cleanup (#2508)
* Some minor rendering code cleanup * asHtml shouldn't be null
1 parent 90dc43b commit 703e08d

File tree

3 files changed

+70
-55
lines changed

3 files changed

+70
-55
lines changed

‎lib/src/markdown_processor.dart

Lines changed: 47 additions & 41 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,6 @@ import 'dart:math';
1111
import 'package:analyzer/dart/element/element.dart';
1212
import 'package:dartdoc/src/element_type.dart';
1313
import 'package:dartdoc/src/model/model.dart';
14-
import 'package:dartdoc/src/tuple.dart';
1514
import 'package:dartdoc/src/warnings.dart';
1615
import 'package:markdown/markdown.dart' as md;
1716

@@ -895,55 +894,51 @@ final RegExp allAfterLastNewline = RegExp(r'\n.*$', multiLine: true);
895894
// https://github.com/dart-lang/dartdoc/issues/1250#issuecomment-269257942
896895
void showWarningsForGenericsOutsideSquareBracketsBlocks(
897896
String text, Warnable element) {
898-
var tagPositions = findFreeHangingGenericsPositions(text);
899-
if (tagPositions.isNotEmpty) {
900-
tagPositions.forEach((int position) {
901-
var priorContext =
902-
'${text.substring(max(position - maxPriorContext, 0), position)}';
903-
var postContext =
904-
'${text.substring(position, min(position + maxPostContext, text.length))}';
905-
priorContext = priorContext.replaceAll(allBeforeFirstNewline, '');
906-
postContext = postContext.replaceAll(allAfterLastNewline, '');
907-
var errorMessage = '$priorContext$postContext';
908-
// TODO(jcollins-g): allow for more specific error location inside comments
909-
element.warn(PackageWarning.typeAsHtml, message: errorMessage);
910-
});
911-
}
897+
findFreeHangingGenericsPositions(text).forEach((int position) {
898+
var priorContext =
899+
'${text.substring(max(position - maxPriorContext, 0), position)}';
900+
var postContext =
901+
'${text.substring(position, min(position + maxPostContext, text.length))}';
902+
priorContext = priorContext.replaceAll(allBeforeFirstNewline, '');
903+
postContext = postContext.replaceAll(allAfterLastNewline, '');
904+
var errorMessage = '$priorContext$postContext';
905+
// TODO(jcollins-g): allow for more specific error location inside comments
906+
element.warn(PackageWarning.typeAsHtml, message: errorMessage);
907+
});
912908
}
913909

914-
List<int> findFreeHangingGenericsPositions(String string) {
910+
Iterable<int> findFreeHangingGenericsPositions(String string) sync* {
915911
var currentPosition = 0;
916912
var squareBracketsDepth = 0;
917-
var results = <int>[];
918913
while (true) {
919-
var nextOpenBracket = string.indexOf('[', currentPosition);
920-
var nextCloseBracket = string.indexOf(']', currentPosition);
921-
var nextNonHTMLTag = string.indexOf(nonHTML, currentPosition);
922-
var nextPositions = [nextOpenBracket, nextCloseBracket, nextNonHTMLTag]
914+
final nextOpenBracket = string.indexOf('[', currentPosition);
915+
final nextCloseBracket = string.indexOf(']', currentPosition);
916+
final nextNonHTMLTag = string.indexOf(nonHTML, currentPosition);
917+
final nextPositions = [nextOpenBracket, nextCloseBracket, nextNonHTMLTag]
923918
.where((p) => p != -1);
924-
if (nextPositions.isNotEmpty) {
925-
final minPos = nextPositions.reduce(min);
926-
if (nextOpenBracket == minPos) {
927-
squareBracketsDepth += 1;
928-
} else if (nextCloseBracket == minPos) {
929-
squareBracketsDepth = max(squareBracketsDepth - 1, 0);
930-
} else if (nextNonHTMLTag == minPos) {
931-
if (squareBracketsDepth == 0) {
932-
results.add(minPos);
933-
}
934-
}
935-
currentPosition = minPos + 1;
936-
} else {
919+
920+
if (nextPositions.isEmpty) {
937921
break;
938922
}
923+
924+
currentPosition = nextPositions.reduce(min);
925+
if (nextOpenBracket == currentPosition) {
926+
squareBracketsDepth += 1;
927+
} else if (nextCloseBracket == currentPosition) {
928+
squareBracketsDepth = max(squareBracketsDepth - 1, 0);
929+
} else if (nextNonHTMLTag == currentPosition) {
930+
if (squareBracketsDepth == 0) {
931+
yield currentPosition;
932+
}
933+
}
934+
currentPosition++;
939935
}
940-
return results;
941936
}
942937

943938
class MarkdownDocument extends md.Document {
944939
factory MarkdownDocument.withElementLinkResolver(
945940
Canonicalization element, List<ModelCommentReference> commentRefs) {
946-
md.Node linkResolver(String name, [String _]) {
941+
md.Node /*?*/ linkResolver(String name, [String /*?*/ _]) {
947942
if (name.isEmpty) {
948943
return null;
949944
}
@@ -969,8 +964,10 @@ class MarkdownDocument extends md.Document {
969964
linkResolver: linkResolver,
970965
imageLinkResolver: imageLinkResolver);
971966

972-
/// Returns a tuple of List<md.Node> and hasExtendedContent
973-
Tuple2<List<md.Node>, bool> parseMarkdownText(
967+
/// Parses markdown text, collecting the first [md.Node] or all of them
968+
/// if [processFullText] is `true`. If more than one node is present,
969+
/// then [DocumentationParseResult.hasExtendedDocs] will be set to `true`.
970+
DocumentationParseResult parseMarkdownText(
974971
String text, bool processFullText) {
975972
var hasExtendedContent = false;
976973
var lines = LineSplitter.split(text).toList();
@@ -985,7 +982,7 @@ class MarkdownDocument extends md.Document {
985982
nodes.add(node);
986983
}
987984
_parseInlineContent(nodes);
988-
return Tuple2(nodes, hasExtendedContent);
985+
return DocumentationParseResult(nodes, hasExtendedContent);
989986
}
990987

991988
// From package:markdown/src/document.dart
@@ -1005,12 +1002,21 @@ class MarkdownDocument extends md.Document {
10051002
}
10061003
}
10071004

1005+
class DocumentationParseResult {
1006+
static const empty = DocumentationParseResult([], false);
1007+
1008+
final List<md.Node> nodes;
1009+
final bool hasExtendedDocs;
1010+
1011+
const DocumentationParseResult(this.nodes, this.hasExtendedDocs);
1012+
}
1013+
10081014
class _InlineCodeSyntax extends md.InlineSyntax {
10091015
_InlineCodeSyntax() : super(r'\[:\s?((?:.|\n)*?)\s?:\]');
10101016

10111017
@override
10121018
bool onMatch(md.InlineParser parser, Match match) {
1013-
var element = md.Element.text('code', htmlEscape.convert(match[1]));
1019+
var element = md.Element.text('code', htmlEscape.convert(match[1] /*!*/));
10141020
parser.addNode(element);
10151021
return true;
10161022
}
@@ -1019,7 +1025,7 @@ class _InlineCodeSyntax extends md.InlineSyntax {
10191025
class _AutolinkWithoutScheme extends md.AutolinkSyntax {
10201026
@override
10211027
bool onMatch(md.InlineParser parser, Match match) {
1022-
var url = match[1];
1028+
var url = match[1] /*!*/;
10231029
var text = htmlEscape.convert(url).replaceFirst(_hideSchemes, '');
10241030
var anchor = md.Element.text('a', text);
10251031
anchor.attributes['href'] = url;

‎lib/src/model/documentation.dart

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,6 @@
55
import 'package:dartdoc/src/markdown_processor.dart';
66
import 'package:dartdoc/src/model/model.dart';
77
import 'package:dartdoc/src/render/documentation_renderer.dart';
8-
import 'package:dartdoc/src/tuple.dart';
98
import 'package:markdown/markdown.dart' as md;
109

1110
class Documentation {
@@ -47,22 +46,24 @@ class Documentation {
4746
void _renderDocumentation(bool processAllDocs) {
4847
var parseResult = _parseDocumentation(processAllDocs);
4948
if (_hasExtendedDocs != null) {
50-
assert(_hasExtendedDocs == parseResult.item2);
49+
assert(_hasExtendedDocs == parseResult.hasExtendedDocs);
5150
}
52-
_hasExtendedDocs = parseResult.item2;
51+
_hasExtendedDocs = parseResult.hasExtendedDocs;
5352

54-
var renderResult = _renderer.render(parseResult.item1, processAllDocs);
53+
var renderResult = _renderer.render(parseResult.nodes, processAllDocs);
5554

5655
if (processAllDocs) {
57-
_asHtml = renderResult.item1;
56+
_asHtml = renderResult.asHtml;
5857
}
59-
_asOneLiner ??= renderResult.item2;
58+
_asOneLiner ??= renderResult.asOneLiner;
6059
}
6160

62-
/// Returns a tuple of List<md.Node> and hasExtendedDocs
63-
Tuple2<List<md.Node>, bool> _parseDocumentation(bool processFullDocs) {
61+
/// Parses the documentation, collecting the first [md.Node] or all of them
62+
/// if [processFullDocs] is `true`. If more than one node is present,
63+
/// then [DocumentationParseResult.hasExtendedDocs] will be set to `true`.
64+
DocumentationParseResult _parseDocumentation(bool processFullDocs) {
6465
if (!_element.hasDocumentation) {
65-
return Tuple2([], false);
66+
return DocumentationParseResult.empty;
6667
}
6768
var text = _element.documentation;
6869
showWarningsForGenericsOutsideSquareBracketsBlocks(text, _element);

‎lib/src/render/documentation_renderer.dart

Lines changed: 13 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,19 +2,18 @@
22
// for details. All rights reserved. Use of this source code is governed by a
33
// BSD-style license that can be found in the LICENSE file.
44

5-
import 'package:dartdoc/src/tuple.dart';
65
import 'package:html/parser.dart' show parse;
76
import 'package:markdown/markdown.dart' as md;
87

98
abstract class DocumentationRenderer {
10-
Tuple2<String, String> render(List<md.Node> nodes, bool processFullDocs);
9+
DocumentationRenderResult render(List<md.Node> nodes, bool processFullDocs);
1110
}
1211

1312
class DocumentationRendererHtml extends DocumentationRenderer {
1413
@override
15-
Tuple2<String, String> render(List<md.Node> nodes, bool processFullDocs) {
14+
DocumentationRenderResult render(List<md.Node> nodes, bool processFullDocs) {
1615
if (nodes.isEmpty) {
17-
return Tuple2('', '');
16+
return DocumentationRenderResult.empty;
1817
}
1918
var rawHtml = md.HtmlRenderer().render(nodes);
2019
var asHtmlDocument = parse(rawHtml);
@@ -49,6 +48,15 @@ class DocumentationRendererHtml extends DocumentationRenderer {
4948
? ''
5049
: asHtmlDocument.body.children.first.innerHtml;
5150

52-
return Tuple2(asHtml, asOneLiner);
51+
return DocumentationRenderResult(asHtml: asHtml, asOneLiner: asOneLiner);
5352
}
5453
}
54+
55+
class DocumentationRenderResult {
56+
static const empty = DocumentationRenderResult(asHtml: '', asOneLiner: '');
57+
58+
final String /*?*/ asHtml;
59+
final String asOneLiner;
60+
61+
const DocumentationRenderResult({this.asHtml, this.asOneLiner = ''});
62+
}

0 commit comments

Comments
 (0)