More correctly remove indentation from documentation comments. (#1612)

* fix indentation bug

* Add end to end test

* dartfmt and rebuild docs

* review comments

Author: jcollins-g

lib/src/utils.dart

@@ -3,14 +3,45 @@
 // BSD-style license that can be found in the LICENSE file.
 library dartdoc.utils;
 
+final RegExp leadingWhiteSpace = new RegExp(r'^([ \t]*)[^ ]');
+
+String stripCommonWhitespace(String str) {
+  StringBuffer buf = new StringBuffer();
+  List<String> lines = str.split('\n');
+  int minimumSeen;
+
+  for (String line in lines) {
+    if (line.isNotEmpty) {
+      Match m = leadingWhiteSpace.firstMatch(line);
+      if (m != null) {
+        if (minimumSeen == null || m.group(1).length < minimumSeen) {
+          minimumSeen = m.group(1).length;
+        }
+      }
+    }
+  }
+  minimumSeen ??= 0;
+  int lineno = 1;
+  for (String line in lines) {
+    if (line.length >= minimumSeen) {
+      buf.write('${line.substring(minimumSeen)}\n');
+    } else {
+      if (lineno < lines.length) {
+        buf.write('\n');
+      }
+    }
+    ++lineno;
+  }
+  return buf.toString();
+}
+
 String stripComments(String str) {
   if (str == null) return null;
-
   StringBuffer buf = new StringBuffer();
 
   if (str.startsWith('///')) {
+    str = stripCommonWhitespace(str);
     for (String line in str.split('\n')) {
-      line = line.trimLeft();
       if (line.startsWith('/// ')) {
         buf.write('${line.substring(4)}\n');
       } else if (line.startsWith('///')) {
@@ -26,9 +57,8 @@ String stripComments(String str) {
     if (str.endsWith('*/')) {
       str = str.substring(0, str.length - 2);
     }
-    str = str.trim();
+    str = stripCommonWhitespace(str);
     for (String line in str.split('\n')) {
-      line = line.trimLeft();
       if (line.startsWith('* ')) {
         buf.write('${line.substring(2)}\n');
       } else if (line.startsWith('*')) {

pubspec.lock

@@ -415,4 +415,4 @@ packages:
     source: hosted
     version: "2.1.13"
 sdks:
-  dart: ">=2.0.0-dev <=2.0.0-dev.24.0"
+  dart: ">=2.0.0-dev <=2.0.0-dev.30.0"

test/model_test.dart

@@ -1502,6 +1502,7 @@ String topLevelFunction(int param1, bool param2, Cool coolBeans,
     Field explicitNonDocumentedInBaseClassGetter;
     Field documentedPartialFieldInSubclassOnly;
     Field ExtraSpecialListLength;
+    Field aProperty;
 
     setUp(() {
       c = exLibrary.classes.firstWhere((c) => c.name == 'Apple');
@@ -1558,6 +1559,27 @@ String topLevelFunction(int param1, bool param2, Cool coolBeans,
           .firstWhere((c) => c.name == 'SpecialList')
           .allInstanceProperties
           .firstWhere((f) => f.name == 'length');
+      aProperty = fakeLibrary.classes
+          .firstWhere((c) => c.name == 'AClassWithFancyProperties')
+          .allInstanceProperties
+          .firstWhere((f) => f.name == 'aProperty');
+    });
+
+    test('indentation is not lost inside indented code samples', () {
+      expect(aProperty.documentation, equals(
+          'This property is quite fancy, and requires sample code to understand.\n'
+              '\n'
+              '```dart\n'
+              'AClassWithFancyProperties x = new AClassWithFancyProperties();\n'
+              '\n'
+              'if (x.aProperty.contains(\'Hello\')) {\n'
+              '  print("I am indented!");\n'
+              '  if (x.aProperty.contains(\'World\')) {\n'
+              '    print ("I am indented even more!!!");\n'
+              '  }\n'
+              '}\n'
+              '```'
+      ));
     });
 
     test('annotations from getters and setters are accumulated in Fields', () {

test/utils_test.dart

@@ -176,4 +176,22 @@ void main() {
       expect(truncateString('foo bar baz qux', 10), 'foo bar ba…');
     });
   });
+
+  group('leadingWhitespace', () {
+    test('strip common leading whitespace, but no more', () {
+      String input = '   3 space indent\n'
+                     '    4 space indent (one preserved)\n'
+                     '       7 space indent (four preserved)\n'
+                     '\t  2 spaces, one tab (same as 3 space)\n'
+                     '    \t4 spaces, one tab (preserve the tab)\n'
+                     '   3 space indent again\n';
+      String output = '3 space indent\n'
+                      ' 4 space indent (one preserved)\n'
+                      '    7 space indent (four preserved)\n'
+                      '2 spaces, one tab (same as 3 space)\n'
+                      ' \t4 spaces, one tab (preserve the tab)\n'
+                      '3 space indent again\n';
+      expect(stripCommonWhitespace(input), equals(output));
+    });
+  });
 }

testing/test_package/lib/fake.dart

@@ -164,6 +164,22 @@ class _APrivateConstClass {
   const _APrivateConstClass();
 }
 
+class AClassWithFancyProperties {
+  /// This property is quite fancy, and requires sample code to understand.
+  ///
+  /// ```dart
+  /// AClassWithFancyProperties x = new AClassWithFancyProperties();
+  ///
+  /// if (x.aProperty.contains('Hello')) {
+  ///   print("I am indented!");
+  ///   if (x.aProperty.contains('World')) {
+  ///     print ("I am indented even more!!!");
+  ///   }
+  /// }
+  /// ```
+  String aProperty;
+}
+
 const _APrivateConstClass CUSTOM_CLASS_PRIVATE = const _APrivateConstClass();
 
 // No dart docs on purpose. Also, a non-primitive const class.

testing/test_package_docs/fake/AClassUsingASuperMixin-class.html

@@ -40,6 +40,7 @@ <h5>fake library</h5>
     <ol>
       <li class="section-title"><a href="fake/fake-library.html#classes">Classes</a></li>
       <li><a href="fake/AClassUsingASuperMixin-class.html">AClassUsingASuperMixin</a></li>
+      <li><a href="fake/AClassWithFancyProperties-class.html">AClassWithFancyProperties</a></li>
       <li><a href="fake/AMixinCallingSuper-class.html">AMixinCallingSuper</a></li>
       <li><a href="fake/Annotation-class.html">Annotation</a></li>
       <li><a href="fake/AnotherInterface-class.html">AnotherInterface</a></li>