Merge pull request #1165 from astashov/add-crossdart

Add ability to "Crossdartify" the source code

Author: keertip

bin/dartdoc.dart

@@ -123,7 +123,10 @@ main(List<String> arguments) async {
   var addCrossdart = args['add-crossdart'] as bool;
   var includeSource = args['include-source'] as bool;
 
-  initializeConfig(addCrossdart: addCrossdart, includeSource: includeSource);
+  initializeConfig(
+      addCrossdart: addCrossdart,
+      includeSource: includeSource,
+      inputDir: inputDir);
 
   var dartdoc = new DartDoc(inputDir, excludeLibraries, sdkDir, generators,
       outputDir, packageMeta, includeLibraries,

lib/resources/styles.css

@@ -178,6 +178,16 @@ h2 .crossdart {
   margin-top: 1em;
 }
 
+.crossdart-link {
+  border-bottom: 1px solid #dfdfdf;
+  text-decoration: none;
+}
+
+.crossdart-link:hover {
+  border-bottom: 1px solid #aaa;
+  text-decoration: none;
+}
+
 @media(max-width: 768px) {
   nav .container {
     width: 100%

lib/src/config.dart

@@ -1,14 +1,18 @@
 library dartdoc.config;
 
+import 'dart:io';
+
 class Config {
+  final Directory inputDir;
   final bool addCrossdart;
   final bool includeSource;
-  Config._(this.addCrossdart, this.includeSource);
+  Config._(this.inputDir, this.addCrossdart, this.includeSource);
 }
 
 Config _config;
 Config get config => _config;
 
-void initializeConfig({bool addCrossdart: false, bool includeSource: true}) {
-  _config = new Config._(addCrossdart, includeSource);
+void initializeConfig(
+    {Directory inputDir, bool addCrossdart: false, bool includeSource: true}) {
+  _config = new Config._(inputDir, addCrossdart, includeSource);
 }

lib/src/model.dart

@@ -1926,6 +1926,24 @@ class Parameter extends ModelElement implements EnclosedElement {
   String toString() => element.name;
 }
 
+Map<String, Map<String, List<Map<String, dynamic>>>> __crossdartJson;
+Map<String, Map<String, List<Map<String, dynamic>>>> get _crossdartJson {
+  if (__crossdartJson == null) {
+    if (config != null) {
+      var crossdartFile =
+          new File(p.join(config.inputDir.path, "crossdart.json"));
+      if (crossdartFile.existsSync()) {
+        __crossdartJson = JSON.decode(crossdartFile.readAsStringSync());
+      } else {
+        __crossdartJson = {};
+      }
+    } else {
+      __crossdartJson = {};
+    }
+  }
+  return __crossdartJson;
+}
+
 abstract class SourceCodeMixin {
   String _sourceCodeCache;
   String get crossdartHtmlTag {
@@ -1942,6 +1960,10 @@ abstract class SourceCodeMixin {
 
   Library get library;
 
+  void clearSourceCodeCache() {
+    _sourceCodeCache = null;
+  }
+
   String get sourceCode {
     if (_sourceCodeCache == null) {
       String contents = getFileContentsFor(element);
@@ -1958,8 +1980,14 @@ abstract class SourceCodeMixin {
         }
 
         // Trim the common indent from the source snippet.
-        String source =
-            contents.substring(node.offset - (node.offset - i), node.end);
+        var start = node.offset - (node.offset - i);
+        String source = contents.substring(start, node.end);
+
+        if (config != null && config.addCrossdart) {
+          source = crossdartifySource(_crossdartJson, source, element, start);
+        } else {
+          source = const HtmlEscape().convert(source);
+        }
         source = stripIndentFromSource(source);
         source = stripDartdocCommentsFromSource(source);
 
@@ -1976,14 +2004,18 @@ abstract class SourceCodeMixin {
     if (_lineNumber != null && _sourceFilePath != null) {
       String packageName = library.package.isSdk ? "sdk" : library.package.name;
       String packageVersion = library.package.version;
-      var root = "${library.package.packageMeta.resolvedDir}/lib"
-          .replaceAll("\\", "/");
-      var sourceFilePath = _sourceFilePath
+      var root = library.package.packageMeta.resolvedDir;
+      if (!library.package.isSdk) {
+        root += "/lib";
+      }
+      root = root.replaceAll("\\", "/");
+      var sourceFilePath = new File(_sourceFilePath)
+          .resolveSymbolicLinksSync()
           .replaceAll("\\", "/")
           .replaceAll(root, "")
           .replaceAll(new RegExp(r"^/*"), "");
       String url =
-          "//crossdart.info/p/$packageName/$packageVersion/$sourceFilePath.html";
+          "//www.crossdart.info/p/$packageName/$packageVersion/$sourceFilePath.html";
       return "${url}#line-${_lineNumber}";
     } else {
       return null;

lib/src/model_utils.dart

@@ -5,12 +5,15 @@
 library dartdoc.model_utils;
 
 import 'dart:io';
+import 'dart:convert';
 
 import 'package:analyzer/dart/element/element.dart';
 import 'package:analyzer/dart/element/type.dart';
 import 'package:analyzer/src/generated/engine.dart';
 import 'package:analyzer/src/generated/sdk.dart';
 import 'package:analyzer/src/generated/source_io.dart';
+import 'package:path/path.dart' as p;
+import 'config.dart';
 
 final Map<String, String> _fileContents = <String, String>{};
 
@@ -79,20 +82,27 @@ bool isPublic(Element e) {
 /// Strip leading dartdoc comments from the given source code.
 String stripDartdocCommentsFromSource(String source) {
   String remainer = source.trimLeft();
-  bool lineComments = remainer.startsWith('///');
-  bool blockComments = remainer.startsWith('/**');
+  HtmlEscape sanitizer = const HtmlEscape();
+  bool lineComments = remainer.startsWith('///') ||
+      remainer.startsWith(sanitizer.convert('///'));
+  bool blockComments = remainer.startsWith('/**') ||
+      remainer.startsWith(sanitizer.convert('/**'));
 
   return source.split('\n').where((String line) {
     if (lineComments) {
-      if (line.startsWith('///')) return false;
+      if (line.startsWith('///') || line.startsWith(sanitizer.convert('///'))) {
+        return false;
+      }
       lineComments = false;
       return true;
     } else if (blockComments) {
-      if (line.contains('*/')) {
+      if (line.contains('*/') || line.contains(sanitizer.convert('*/'))) {
         blockComments = false;
         return false;
       }
-      if (line.startsWith('/**')) return false;
+      if (line.startsWith('/**') || line.startsWith(sanitizer.convert('/**'))) {
+        return false;
+      }
       return false;
     }
 
@@ -109,3 +119,45 @@ String stripIndentFromSource(String source) {
     return line.startsWith(indent) ? line.substring(indent.length) : line;
   }).join('\n');
 }
+
+/// Add links to crossdart.info to the given source fragment
+String crossdartifySource(
+    Map<String, Map<String, List<Map<String, dynamic>>>> json,
+    String source,
+    Element element,
+    int start) {
+  var sanitizer = const HtmlEscape();
+  String newSource;
+  if (json.isNotEmpty) {
+    var node = element.computeNode();
+    var file =
+        element.source.fullName.replaceAll("${config.inputDir.path}/", "");
+    var filesData = json[file];
+    if (filesData != null) {
+      var data = filesData["references"]
+          .where((r) => r["offset"] >= start && r["end"] <= node.end);
+      if (data.isNotEmpty) {
+        var previousStop = 0;
+        var stringBuffer = new StringBuffer();
+        for (var item in data) {
+          stringBuffer.write(sanitizer
+              .convert(source.substring(previousStop, item["offset"] - start)));
+          stringBuffer
+              .write("<a class='crossdart-link' href='${item["remotePath"]}'>");
+          stringBuffer.write(sanitizer.convert(
+              source.substring(item["offset"] - start, item["end"] - start)));
+          stringBuffer.write("</a>");
+          previousStop = item["end"] - start;
+        }
+        stringBuffer.write(
+            sanitizer.convert(source.substring(previousStop, source.length)));
+
+        newSource = stringBuffer.toString();
+      }
+    }
+  }
+  if (newSource == null) {
+    newSource = sanitizer.convert(source);
+  }
+  return newSource;
+}

lib/templates/_source_code.html

@@ -1,5 +1,5 @@
 {{#hasSourceCode}}
 <section class="summary source-code" id="source">
   <h2><span>Source</span> {{{crossdartHtmlTag}}}</h2>
-  <pre><code class="prettyprint lang-dart">{{ sourceCode }}</code></pre>
+  <pre class="prettyprint lang-dart">{{{ sourceCode }}}</pre>
 </section>{{/hasSourceCode}}

test/model_test.dart

@@ -12,6 +12,7 @@ import 'package:dartdoc/src/model.dart';
 import 'package:dartdoc/src/model_utils.dart';
 import 'package:dartdoc/src/package_meta.dart';
 import 'package:test/test.dart';
+import 'package:path/path.dart' as p;
 
 import 'src/utils.dart' as utils;
 
@@ -805,6 +806,7 @@ void main() {
     });
 
     test('has source code', () {
+      initializeConfig(addCrossdart: false);
       expect(topLevelFunction.sourceCode, startsWith('@deprecated'));
       expect(topLevelFunction.sourceCode, endsWith('''
 String topLevelFunction(int param1, bool param2, Cool coolBeans,
@@ -844,6 +846,13 @@ String topLevelFunction(int param1, bool param2, Cool coolBeans,
           .singleWhere((m) => m.name == 'convertToMap');
     });
 
+    tearDown(() {
+      var file = new File(p.join(Directory.current.path, "crossdart.json"));
+      if (file.existsSync()) {
+        file.deleteSync();
+      }
+    });
+
     test('has a fully qualified name', () {
       expect(m1.fullyQualifiedName, 'ex.B.m1');
     });
@@ -920,7 +929,22 @@ String topLevelFunction(int param1, bool param2, Cool coolBeans,
     });
 
     test('method source code indents correctly', () {
-      expect(convertToMap.sourceCode, 'Map<X, Y> convertToMap() => null;');
+      initializeConfig(addCrossdart: false);
+      expect(convertToMap.sourceCode,
+          'Map&lt;X, Y&gt; convertToMap() =&gt; null;');
+    });
+
+    test('method source code crossdartifies correctly', () {
+      convertToMap.clearSourceCodeCache();
+      new File(p.join(Directory.current.path, "crossdart.json"))
+          .writeAsStringSync("""
+              {"testing/test_package/lib/fake.dart":
+                {"references":[{"offset":5806,"end":5809,"remotePath":"http://www.example.com/fake.dart"}]}}
+      """);
+
+      initializeConfig(addCrossdart: true, inputDir: Directory.current);
+      expect(convertToMap.sourceCode,
+          "<a class='crossdart-link' href='http://www.example.com/fake.dart'>Map</a>&lt;X, Y&gt; convertToMap() =&gt; null;");
     });
 
     group(".crossdartHtmlTag()", () {
@@ -929,7 +953,7 @@ String topLevelFunction(int param1, bool param2, Cool coolBeans,
         String packageName = m1.library.package.name;
         String packageVersion = m1.library.package.version;
         expect(m1.crossdartHtmlTag,
-            contains("//crossdart.info/p/$packageName/$packageVersion"));
+            contains("//www.crossdart.info/p/$packageName/$packageVersion"));
       });
 
       test('it returns an empty string when Crossdart support is disabled', () {