Merge pull request #699 from dart-lang/show-source

display source for method

Author: sethladd

lib/resources/styles.css

@@ -531,3 +531,35 @@ ol#sidebar li:first-child {
   .row-offcanvas-left.active{left:50%;}
   .sidebar-offcanvas{position:absolute;top:0;width:50%;}
 }
+
+/* toggling source code */
+
+.source-code pre {
+  margin: 16px 0 16px 0;
+}
+
+.source-code h4 {
+  color: #455A64;
+  text-transform: uppercase;
+  font-size: 14px;
+}
+
+.source-code h4:hover {
+  cursor: pointer;
+}
+
+.source-code-toggle {
+  font-size: 80%;
+  float: left;
+  width: 1.2em;
+  padding-top: 2px; /* how to avoid this? how to vertically align? */
+  opacity: 0.7;
+}
+
+.source-code-toggle.closed::before {
+  content: '\25B6';
+}
+
+.source-code-toggle.open::before {
+  content: '\25BC';
+}

lib/src/html_generator.dart

@@ -87,7 +87,8 @@ class Templates {
       'readable_writable',
       'documentation',
       'name_summary',
-      'sidebar_for_class'
+      'sidebar_for_class',
+      'source_code'
     ];
 
     for (var partial in partials) {

lib/src/model.dart

@@ -1106,7 +1106,26 @@ class Enum extends Class {
   }
 }
 
-class ModelFunction extends ModelElement {
+abstract class SourceCodeMixin {
+  String get sourceCode {
+    String contents = element.source.contents.data;
+    var node = element.node; // TODO: computeNode once we go to 0.25.2
+    // find the start of the line, so that we can line up all the indents
+    int i = node.offset;
+    while (i > 0) {
+      i -= 1;
+      if (contents[i] == '\n' || contents[i] == '\r') {
+        i += 1;
+        break;
+      }
+    }
+    return contents.substring(node.offset - (node.offset - i), node.end);
+  }
+
+  Element get element;
+}
+
+class ModelFunction extends ModelElement with SourceCodeMixin {
   ModelFunction(FunctionElement element, Library library)
       : super(element, library) {
     _modelType = new ElementType(_func.type, this);
@@ -1301,7 +1320,7 @@ class Constructor extends ModelElement {
   }
 }
 
-class Method extends ModelElement {
+class Method extends ModelElement with SourceCodeMixin {
   bool _isInherited = false;
 
   MethodElement get _method => (element as MethodElement);

lib/templates/_footer.html

@@ -58,10 +58,26 @@
   scrollBy(0, -68);
 }
 
+function initSourceToggle() {
+  var toggle = document.querySelector('.source-code h4');
+  var toggleArrow = document.querySelector('.source-code-toggle');
+  var code = document.querySelector('.source-code pre');
+
+  if (toggle && toggleArrow && code) {
+    toggle.addEventListener('click', function(e) {
+      var closed = toggleArrow.classList.contains('closed');
+      toggleArrow.classList.toggle('closed', !closed);
+      toggleArrow.classList.toggle('open', closed);
+      code.style.display = closed ? 'block' : 'none';
+    });
+  }
+}
+
 document.addEventListener("DOMContentLoaded", function() {
   prettyPrint();
   initScroller();
   initSideNav();
+  initSourceToggle();
 
   // Make sure the anchors scroll past the fixed page header (#648).
   if (location.hash) shiftWindow();

lib/templates/_source_code.html

@@ -0,0 +1,4 @@
+<section class="source-code">
+  <h4><span class="source-code-toggle closed"></span> Source</h4>
+  <pre style="display:none"><code class="prettyprint lang-dart">{{ sourceCode }}</code></pre>
+</section>

lib/templates/function.html

@@ -69,6 +69,10 @@ <h5>{{{library.linkedName}}}</h5>
     {{>documentation}}
     {{/function}}
 
+    {{#function}}
+    {{>source_code}}
+    {{/function}}
+
   </div> <!-- /.col-xs-12.col-sm-9 -->
 
 </div> <!-- /.row-offcanvas -->

lib/templates/method.html

@@ -22,6 +22,10 @@ <h5>{{{class.linkedName}}}</h5>
     {{>documentation}}
     {{/method}}
 
+    {{#method}}
+    {{>source_code}}
+    {{/method}}
+
   </div> <!-- /.col-xs-12.col-sm-9 -->
 
 </div> <!-- /.row-offcanvas -->

pubspec.lock

@@ -4,7 +4,7 @@ packages:
   analyzer:
     description: analyzer
     source: hosted
-    version: "0.25.1"
+    version: "0.25.0"
   ansicolor:
     description: ansicolor
     source: hosted
@@ -13,14 +13,14 @@ packages:
     description: args
     source: hosted
     version: "0.13.2"
+  async:
+    description: async
+    source: hosted
+    version: "1.2.0"
   barback:
     description: barback
     source: hosted
-    version: "0.15.2+4"
-  charcode:
-    description: charcode
-    source: hosted
-    version: "1.1.0"
+    version: "0.15.2+5"
   cli_util:
     description: cli_util
     source: hosted
@@ -40,39 +40,39 @@ packages:
   csslib:
     description: csslib
     source: hosted
-    version: "0.12.0+1"
+    version: "0.12.1"
   den_api:
     description: den_api
     source: hosted
     version: "0.1.0"
   github:
     description: github
     source: hosted
-    version: "2.2.2"
+    version: "2.2.3+1"
   glob:
     description: glob
     source: hosted
-    version: "1.0.4"
+    version: "1.0.5"
   grinder:
     description: grinder
     source: hosted
     version: "0.7.2"
   html:
     description: html
     source: hosted
-    version: "0.12.1+1"
+    version: "0.12.1+2"
   http:
     description: http
     source: hosted
-    version: "0.11.2"
+    version: "0.11.3"
   http_multi_server:
     description: http_multi_server
     source: hosted
     version: "1.3.2"
   http_parser:
     description: http_parser
     source: hosted
-    version: "0.0.2+7"
+    version: "0.0.2+8"
   librato:
     description: librato
     source: hosted
@@ -101,26 +101,18 @@ packages:
     description: mustache4dart
     source: hosted
     version: "1.0.10"
-  package_config:
-    description: package_config
-    source: hosted
-    version: "0.1.1"
   path:
     description: path
     source: hosted
-    version: "1.3.5"
+    version: "1.3.6"
   petitparser:
     description: petitparser
     source: hosted
     version: "1.4.3"
-  plugin:
-    description: plugin
-    source: hosted
-    version: "0.1.0"
   pool:
     description: pool
     source: hosted
-    version: "1.0.2"
+    version: "1.1.0"
   pub_cache:
     description: pub_cache
     source: hosted
@@ -140,7 +132,7 @@ packages:
   shelf:
     description: shelf
     source: hosted
-    version: "0.6.1+2"
+    version: "0.6.2"
   shelf_static:
     description: shelf_static
     source: hosted
@@ -164,7 +156,7 @@ packages:
   stack_trace:
     description: stack_trace
     source: hosted
-    version: "1.3.3"
+    version: "1.3.4"
   string_scanner:
     description: string_scanner
     source: hosted
@@ -176,19 +168,19 @@ packages:
   test:
     description: test
     source: hosted
-    version: "0.12.3"
+    version: "0.12.3+7"
   unscripted:
     description: unscripted
     source: hosted
-    version: "0.6.1+1"
+    version: "0.6.2"
   utf:
     description: utf
     source: hosted
     version: "0.9.0+2"
   watcher:
     description: watcher
     source: hosted
-    version: "0.9.6"
+    version: "0.9.7"
   when:
     description: when
     source: hosted

pubspec.yaml

@@ -5,9 +5,9 @@ author: Dart Team <[email protected]>
 description: A documentation generator for Dart.
 homepage: https://github.com/dart-lang/dartdoc
 environment:
-  sdk: '>=1.9.0 <2.0.0'
+  sdk: '>=1.9.0 <2.0.0' # when we go to 1.12, bump analyzer version
 dependencies:
-  analyzer: '>=0.22.0 <0.26.0'
+  analyzer: '0.25.0' # > 0.25 has new APIs, but only works in 1.12
   args: ^0.13.0
   cli_util: ^0.0.1
   html: ^0.12.1

test/model_test.dart

@@ -408,22 +408,36 @@ void main() {
     test('docs do not lose brackets in code blocks', () {
       expect(topLevelFunction.documentation, contains("['hello from dart']"));
     });
+
+    test('has source code', () {
+      expect(topLevelFunction.sourceCode, startsWith(
+          '/// Top-level function 3 params and 1 optional positional param.'));
+      expect(topLevelFunction.sourceCode, endsWith('''
+String topLevelFunction(int param1, bool param2, Cool coolBeans,
+    [double optionalPositional = 0.0]) {
+  return null;
+}'''));
+    });
   });
 
   group('Method', () {
-    Class classB, klass;
-    Method m, isGreaterThan, m4, m5, m6;
+    Class classB, klass, HasGenerics;
+    Method m, isGreaterThan, m4, m5, m6, convertToMap;
 
     setUp(() {
       klass = exLibrary.classes.singleWhere((c) => c.name == 'Klass');
       classB = exLibrary.classes.singleWhere((c) => c.name == 'B');
+      HasGenerics =
+          fakeLibrary.classes.singleWhere((c) => c.name == 'HasGenerics');
       m = classB.instanceMethods.first;
       isGreaterThan = exLibrary.classes
               .singleWhere((c) => c.name == 'Apple').instanceMethods
           .singleWhere((m) => m.name == 'isGreaterThan');
       m4 = classB.instanceMethods[1];
       m5 = klass.instanceMethods.singleWhere((m) => m.name == 'another');
       m6 = klass.instanceMethods.singleWhere((m) => m.name == 'toString');
+      convertToMap = HasGenerics.instanceMethods
+          .singleWhere((m) => m.name == 'convertToMap');
     });
 
     test('overriden method', () {
@@ -457,6 +471,11 @@ void main() {
       expect(comment, equals('Another method'));
       expect(comment2, equals('A shadowed method'));
     });
+
+    test('method source code indents correctly', () {
+      expect(convertToMap.sourceCode,
+          startsWith('  /// Converts itself to a map.'));
+    });
   });
 
   group('Field', () {