Monday, November 5, 2012

Adding to the Dart SDK Test Suite

While updating my Hipster MVC library, I found that the old style of dartdoc documentation no longer worked. The dartdoc tool is part of the Dart SDK. It parses source code as Markdown, producing very pretty documentation.

The problem is that documentation marked with triple slashes was not formatted correctly. The following commented Dart code is not producing properly formatted documentation:

The most obvious problem is that code samples, introduced by four spaces, are not being formatted as code samples.

After a bit of investigation, I found that the cause is the CommentMap class improperly stripping newlines from triple-slashed comments. Given the above multi-line comment, the CommentMap class was passing a single line to the markdown parser:

Testing var testing = 'this is source code';

Since it was a single line, markdown was not seeing the indented code line.

Anyhow, given the above precondition, I think that I want the following test for my dartdoc code fix:

In other words, I very much want that newline character in the expect() statement.

In order for that test to work, I am going to need a bit more setup in dart/sdk/lib/_internal/dartdoc/test/comment_map_test.dart. I start with the license, which appears in all of the tests, the name of the library, and some imports:

// Copyright (c) 2012, 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.
/// Unit tests for comment map.
library commentMapTests;
import 'dart:uri';
import '../lib/mirrors.dart';
import '../../compiler/implementation/scanner/scannerlib.dart' as dart2js;

The imports are taken from the other libraries in the dartdoc test suite, though I do apply some process of elimination to figure out which ones really need to be included.

Next, I need to import the unittest library. Again, I copy the import from other dartdoc tests, comment and all:

Before submitting a patch back to the Dart maintainers I need to modify that path as I found yesterday.

Finally, I need to pull in the CommentMap class. It is "part" of the dartdoc library (as opposed to a separate library that needs to be imported). So I need to pull it into my test with the part keyword:

Once more, I copy comments from similar statements to (hopefully) increase the likelihood that my patch will be accepted.

The last thing that I need to do is define the FakeSourceLocation class that will be used by the CommentMap. Reading through the CommentMap code, the source location object needs to define the sourceUri, offset, and sourceText properties. For this fake/test class, I define them as:

The sourceUri and sourceText are pretty straight-forward. The offset is the number of characters from the start of the string under the source code. In this case, there are 57 characters of comments before the foo getter is reached.