Modify the dartdoc code rendering. Syntax highlightning

dart/utils/dartdoc/dartdoc.dart

 // Copyright (c) 2011, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 /**
  * To use it, from this directory, run:
  *
  *     $ ./dartdoc <path to .dart file>
  *
  * This will create a "docs" directory with the docs for your libraries. To
@@ skipping 552 matching lines @@
    * is `true` (and [includeSource] is set), also includes the source code.
    */
   docCode(SourceSpan span, String comment, [bool showCode = false]) {
     writeln('<div class="doc">');
     if (comment != null) {
       writeln(md.markdownToHtml(comment));
     }
 
     if (includeSource && showCode) {
       writeln('<pre class="source">');
-      write(formatCode(span));
+      writeln(md.escapeHtml('${unindentCode(span)}'));

[Bob Nystrom, 2011/12/19 23:17:34]

You don't need to interpolate here.

[michael.haubenwallner, 2011/12/20 08:54:54]

Small problem on the client side: when the code string is accessed through
'pre.text' everything element-like gets stripped, e.g. 'List<String> getNames()
{}' results in 'List getNames() {}'. Accessing through pre.innerHTML rewrites it
to 'List<string> getNames() {} </string>'.
Escaping the code string seems reasonable, what do you think?

[Bob Nystrom, 2011/12/20 18:46:36]

Right, sorry if I wasn't clear. Escaping is definitely good. What you don't need
(as far as I can tell) is to *interpolate*. You just be able to do:

writeln(md.escapeHtml(unindentCode(span)));

A string literal whose entire contents are just an interpolated variable
shouldn't be needed. (If it is, it's a bug.)

       writeln('</pre>');
     }
 
     writeln('</div>');
   }
 
   /** Get the doc comment associated with the given type. */
   String getTypeComment(Type type) => _comments.find(type.span);
 
   /** Get the doc comment associated with the given method. */
@@ skipping 108 matching lines @@
     if (typeArgs != null) {
       final args = Strings.join(map(typeArgs, (arg) => typeName(arg)), ', ');
       return '${type.genericType.name}&lt;$args&gt;';
     }
 
     // Regular type.
     return type.name;
   }
 
   /**
-   * Takes a string of Dart code and turns it into sanitized HTML.
+   * Unindents a bunch of Dart code lines

[Bob Nystrom, 2011/12/19 23:17:34]

This needs a better comment. Just take the "Remove leading..." comment from the
body and use that.

[michael.haubenwallner, 2011/12/20 08:54:54]

Done.

[Bob Nystrom, 2011/12/20 18:46:36]

When you've made changes during a review, you have to explicitly upload those
too so that the review sees them. There are instructions here:
http://dev.chromium.org/developers/contributing-code

The relevant bits are:


You will likely get email back from the reviewer with comments. Fix these and
update the patch set in the issue by uploading again.  The upload will explain
that it is updating the current CL and ask you for a message explaining the
change.

GCL

Add any new files that need to be added to your checkout

gcl change changelist_name

gcl upload changelist_name

GIT CL

If you need to update code the code on an already uploaded CL, simply
edit the code, commit it again locally, and then run git cl upload again e.g.

echo "" > GOATS
git add GOATS
git commit -m 'add newline fix to GOATS'
git cl upload


Once you're ready for another review, use Publish+Mail Comments again to send
another notification (you can say something like "new snapshot uploaded").  When
the reviewer is happy with your patch, they will say "LGTM" ("Looks Good To
Me").

:)

    */
-  formatCode(SourceSpan span) {
+  unindentCode(SourceSpan span) {
     // Remove leading indentation to line up with first line.
     final column = getSpanColumn(span);
     final lines = span.text.split('\n');
     // TODO(rnystrom): Dirty hack.
     for (final i = 1; i < lines.length; i++) {
       lines[i] = unindent(lines[i], column);
     }
 
     final code = Strings.join(lines, '\n');
+    return code;
+  }
+
+  /**
+   * Takes a string of Dart code and turns it into sanitized HTML.
+   */
+  formatCode(SourceSpan span) {
+    final code = unindentCode(span);
 
     // Syntax highlight.
     return classifySource(new SourceFile('', code));
   }
 
   /**
    * This will be called whenever a doc comment hits a `[name]` in square
    * brackets. It will try to figure out what the name refers to and link or
    * style it appropriately.
    */
@@ skipping 58 matching lines @@
 
     return new md.Element.text('code', name);
   }
 
   // TODO(rnystrom): Move into SourceSpan?
   int getSpanColumn(SourceSpan span) {
     final line = span.file.getLine(span.start);
     return span.file.getColumn(line, span.start);
   }
 }