Lots of stuff hooking up markdown to dartdoc.

Lots of stuff hooking up markdown to dartdoc.

- Add support for [foo] implicit links to markdown.
- Add hook so that outside code can define what markup a [foo] link creates.
- Make dartdoc look up [foo] names to resolve the identifier.
- Fix unmatched tag unwinding bug.
- Add [:...:] code support to dartdoc.
- Fix text and URLs for generic types in docs.
- Sort classes by name.
- Don't generate docs for private types.
- Fix generated docs for inheritance chain.
- Make source code in generated docs optional.
- Fix showing base class in docs.
- Implement insertRange() for List in frog.
- Add dartdoc shell script.

Committed: https://code.google.com/p/dart/source/detail?r=1886

[Bob Nystrom, 2011-11-28 21:08:05]

Sorry for the slew of changes in one patch. I did most of this over the holiday
break in bits and pieces so it wasn't easy to separate it out into multiple
changes.

With this patch, dartdoc is much closer to generating output we can share with
the world. I still have a couple more changes I want to get in (navigation
mainly) but it's almost there.

[nweiz, 2011-11-28 22:50:45]

http://codereview.chromium.org/8725007/diff/2001/frog/lib/corelib_impl.dart
File frog/lib/corelib_impl.dart (right):

http://codereview.chromium.org/8725007/diff/2001/frog/lib/corelib_impl.dart#n...
frog/lib/corelib_impl.dart:79: for (var i = 0; i < length; i++) args[i + 2] =
initialValue;
Are single-line loops supported by the styleguide? I like them, but I've been
avoiding them because I thought they were disallowed.

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/README.txt
File utils/dartdoc/README.txt (right):

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/README.txt#new...
utils/dartdoc/README.txt:3: To use it, from this directory, run:
What would it take for this to be runnable from an arbitrary directory?

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart
File utils/dartdoc/dartdoc.dart (right):

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:293: final isSubclass = (type.parent != null) &&
(!type.parent.isObject);
Unnecessary parens

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:350: [String namedConstructor = null]) {
It's confusing to me that namedConstructor is non-null for nameless
constructors. Rename to constructorName?

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:452: nameType(Type type) {
I think "typeName" is a better name for this... I like noun-phrase names for
methods that just compute a value.

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:455: final typeParams =
type.genericType.typeParameters;
If type.isGeneric is true, type.genericType.typeParameters will always be
identical to type.typeParameters.

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:463: final args = Strings.join(map(typeArgs, (arg) =>
arg.name), ', ');
Shouldn't this use nameType(arg) or crossRefType(arg)?

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:472: libraryUrl(Library library) {
Seems like this should be a one-liner.

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:479: final library = sanitize(type.library.name);
Unused variable.

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:484: memberUrl(Member member) {
=>

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:485: return
'${typeUrl(member.declaringType)}.${member.name}';
Shouldn't this be '#${memberAnchor(member)}'?

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:493: if (name == null) return '';
Why not return "_top" or something like that?

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:495: // Remove any type args or params that have been
mangled into the name.
How sure are we that this can't produce duplicate ids?

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:504: return
'${typeAnchor(member.declaringType)}.${member.name}';
I don't like periods in ids. Yes, it's allowed by HTML, but it's not allowed by
CSS and it's basically free to use a hyphen instead.

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:508: crossRefType(Type type) {
typeReference

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:511: final library = sanitize(type.library.name);
Unused variable

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:520: annotateType(Type enclosingType, Type type) {
typeAnnotation

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:561: if (member != null) {
if (member == null) continue;

Indentation is bad ;)

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:572: }
Shouldn't this stuff be in memberAnchor?

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:574: return
makeLink('#${_currentType.name}.$memberName');
memberAnchor(member)

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:582: return makeLink('#${type.name}');
typeAnchor(type)

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:590: return new md.Element.text('code', name);
At some point, this should probably warn to protect from typos.

http://codereview.chromium.org/8725007/diff/2001/utils/markdown/inline_parser...
File utils/markdown/inline_parser.dart (right):

http://codereview.chromium.org/8725007/diff/2001/utils/markdown/inline_parser...
utils/markdown/inline_parser.dart:103: writeTextRange(int start, int end) {
Shadowing of start here is a little confusing.

http://codereview.chromium.org/8725007/diff/2001/utils/markdown/inline_parser...
utils/markdown/inline_parser.dart:294: if (link == null) {
:(

[Jennifer Messerly, 2011-11-28 23:08:13]

lgtm

http://codereview.chromium.org/8725007/diff/2001/frog/lib/corelib_impl.dart
File frog/lib/corelib_impl.dart (right):

http://codereview.chromium.org/8725007/diff/2001/frog/lib/corelib_impl.dart#n...
frog/lib/corelib_impl.dart:79: for (var i = 0; i < length; i++) args[i + 2] =
initialValue;
you should be able to surround this with an if:
  if (initialValue != null) {
    for (var i = 0; i < length; i++) args[i + 2] = initialValue;
  }
... and rely on it to be initialized to undefined.

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc
File utils/dartdoc/dartdoc (right):

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc#newcode12
utils/dartdoc/dartdoc:12: ../../frog/frogsh --libdir=../../frog/lib
--out=static/interact.js \
probably want to get `dirname $0` make make paths relative to that. Or use
"pushd". It's good if scripts are safe to run from any directory.

BTW, I really like this auto-update of the JS file step! I wonder if Frog should
do something like this automatically, analogous to Python's ".pyc" files.

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart
File utils/dartdoc/dartdoc.dart (right):

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:293: final isSubclass = (type.parent != null) &&
(!type.parent.isObject);
You don't want to show things that are extending object? Consider:

http://msdn.microsoft.com/en-us/library/system.string.aspx
http://docs.oracle.com/javase/6/docs/api/java/lang/String.html
http://www.ruby-doc.org/core-1.9.3/String.html

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:428: if (field.isStatic && (type.name != null)) {
!type.isTop ? That'd be more self documenting. I wouldn't rely on the type name
being null (imho)

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:472: libraryUrl(Library library) {
this can be a one liner:
libraryUrl(Library library) => '${sanitize(library.name)}.html';

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:493: if (name == null) return '';
I'd use type.isTop here too (and anywhere else :) )

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:539: md.Node resolveNameReference(String name) {
This reminds me how much I dislike prefixes. At least it's only 2 chars...

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:605: writeln(html);
as one line? writeln(md.markdownToHtml(comment));

http://codereview.chromium.org/8725007/diff/2001/utils/markdown/block_parser....
File utils/markdown/block_parser.dart (right):

http://codereview.chromium.org/8725007/diff/2001/utils/markdown/block_parser....
utils/markdown/block_parser.dart:119: List<String> parseChildLines(BlockParser
parser) {
heh :)

http://codereview.chromium.org/8725007/diff/2001/utils/markdown/lib.dart
File utils/markdown/lib.dart (right):

http://codereview.chromium.org/8725007/diff/2001/utils/markdown/lib.dart#newc...
utils/markdown/lib.dart:34: Node setImplicitLinkResolver(Node resolver(String
text)) {
what's the deal here? Is this a frog bug? (maybe a TODO if that's the case)

[Bob Nystrom, 2011-11-29 02:44:08]

Best reviews ever. Thanks!

http://codereview.chromium.org/8725007/diff/2001/frog/lib/corelib_impl.dart
File frog/lib/corelib_impl.dart (right):

http://codereview.chromium.org/8725007/diff/2001/frog/lib/corelib_impl.dart#n...
frog/lib/corelib_impl.dart:79: for (var i = 0; i < length; i++) args[i + 2] =
initialValue;
On 2011/11/28 22:50:45, nweiz wrote:
> Are single-line loops supported by the styleguide? I like them, but I've been
> avoiding them because I thought they were disallowed.

Oops, you're right. Fixed.

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/README.txt
File utils/dartdoc/README.txt (right):

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/README.txt#new...
utils/dartdoc/README.txt:3: To use it, from this directory, run:
On 2011/11/28 22:50:45, nweiz wrote:
> What would it take for this to be runnable from an arbitrary directory?

Some shell shenanigans. It's a little tricky even running frog from other
directories, but I can look into it at some point.

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc
File utils/dartdoc/dartdoc (right):

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc#newcode12
utils/dartdoc/dartdoc:12: ../../frog/frogsh --libdir=../../frog/lib
--out=static/interact.js \
On 2011/11/28 23:08:13, John Messerly wrote:
> probably want to get `dirname $0` make make paths relative to that. Or use
> "pushd". It's good if scripts are safe to run from any directory.
> 
> BTW, I really like this auto-update of the JS file step! I wonder if Frog
should
> do something like this automatically, analogous to Python's ".pyc" files.

Done.

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart
File utils/dartdoc/dartdoc.dart (right):

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:293: final isSubclass = (type.parent != null) &&
(!type.parent.isObject);
On 2011/11/28 22:50:45, nweiz wrote:
> Unnecessary parens

Done.

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:293: final isSubclass = (type.parent != null) &&
(!type.parent.isObject);
On 2011/11/28 23:08:13, John Messerly wrote:
> You don't want to show things that are extending object? Consider:
> 
> http://msdn.microsoft.com/en-us/library/system.string.aspx
> http://docs.oracle.com/javase/6/docs/api/java/lang/String.html
> http://www.ruby-doc.org/core-1.9.3/String.html
> 

I don't mind showing the full inheritance chain (including subclasses) somewhere
in the generated docs, but I thought it felt a little weird to have a bunch of
"Extends Object." sitting directly after the class name for a bunch of types.
Seemed kind of pointless.

I think it's important to show the non-object superclasses and any implemented
interfaces right at the top of a type's documentation because I think most users
care about that, but the fact that it extends object didn't seem to add a lot of
value to me. I'm trying to keep it as uncluttered as possible.

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:350: [String namedConstructor = null]) {
On 2011/11/28 22:50:45, nweiz wrote:
> It's confusing to me that namedConstructor is non-null for nameless
> constructors. Rename to constructorName?

Done.

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:428: if (field.isStatic && (type.name != null)) {
On 2011/11/28 23:08:13, John Messerly wrote:
> !type.isTop ? That'd be more self documenting. I wouldn't rely on the type
name
> being null (imho)

Oh, is that what isTop means? Done.

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:452: nameType(Type type) {
On 2011/11/28 22:50:45, nweiz wrote:
> I think "typeName" is a better name for this... I like noun-phrase names for
> methods that just compute a value.

Done.

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:455: final typeParams =
type.genericType.typeParameters;
On 2011/11/28 22:50:45, nweiz wrote:
> If type.isGeneric is true, type.genericType.typeParameters will always be
> identical to type.typeParameters.

Right, but Type doesn't define typeParameters so it's a type warning. Doing
.genericType casts to DefinedType for me.

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:463: final args = Strings.join(map(typeArgs, (arg) =>
arg.name), ', ');
On 2011/11/28 22:50:45, nweiz wrote:
> Shouldn't this use nameType(arg) or crossRefType(arg)?

Good catch. Forgot about nested types. Done.

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:472: libraryUrl(Library library) {
On 2011/11/28 23:08:13, John Messerly wrote:
> this can be a one liner:
> libraryUrl(Library library) => '${sanitize(library.name)}.html';

Done.

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:479: final library = sanitize(type.library.name);
On 2011/11/28 22:50:45, nweiz wrote:
> Unused variable.

Done.

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:484: memberUrl(Member member) {
On 2011/11/28 22:50:45, nweiz wrote:
> =>

Done.

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:485: return
'${typeUrl(member.declaringType)}.${member.name}';
On 2011/11/28 22:50:45, nweiz wrote:
> Shouldn't this be '#${memberAnchor(member)}'?

It's a little hairy but typeUrl already includes part of the anchor.

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:493: if (name == null) return '';
On 2011/11/28 22:50:45, nweiz wrote:
> Why not return "_top" or something like that?

That could be an actual type name. An empty string actually works for now at
least, but something better would be nice.

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:495: // Remove any type args or params that have been
mangled into the name.
On 2011/11/28 22:50:45, nweiz wrote:
> How sure are we that this can't produce duplicate ids?

I'm not totally sure. I think the "$" are only used for generic types, and Dart
doesn't let you overload by type parameter arity, so I think this is safe, but
I'm not positive.

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:504: return
'${typeAnchor(member.declaringType)}.${member.name}';
On 2011/11/28 22:50:45, nweiz wrote:
> I don't like periods in ids. Yes, it's allowed by HTML, but it's not allowed
by
> CSS and it's basically free to use a hyphen instead.

Done.

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:508: crossRefType(Type type) {
On 2011/11/28 22:50:45, nweiz wrote:
> typeReference

Done.

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:511: final library = sanitize(type.library.name);
On 2011/11/28 22:50:45, nweiz wrote:
> Unused variable

Done.

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:520: annotateType(Type enclosingType, Type type) {
On 2011/11/28 22:50:45, nweiz wrote:
> typeAnnotation

Did "annotation" instead.

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:539: md.Node resolveNameReference(String name) {
On 2011/11/28 23:08:13, John Messerly wrote:
> This reminds me how much I dislike prefixes. At least it's only 2 chars...

Yeah. Needed it to distinguish between frog and markdown's nodes. Sucks that I
have to fully-qualify *all* markdown names to fix that. :(

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:561: if (member != null) {
On 2011/11/28 22:50:45, nweiz wrote:
> if (member == null) continue;
> 
> Indentation is bad ;)

Continue in an if? ;)

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:572: }
On 2011/11/28 22:50:45, nweiz wrote:
> Shouldn't this stuff be in memberAnchor?

This goes in the other direction. memberAnchor will always give the "normal"
member name which could be stuff like "get$foo" or "operator$+" or whatever.
That's good because it keeps them unambiguous.

This method expects to see things like "foo" or "+" and then tries to find an
appropriate real member with that name.

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:574: return
makeLink('#${_currentType.name}.$memberName');
On 2011/11/28 22:50:45, nweiz wrote:
> memberAnchor(member)

Done.

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:582: return makeLink('#${type.name}');
On 2011/11/28 22:50:45, nweiz wrote:
> typeAnchor(type)

Done.

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:590: return new md.Element.text('code', name);
On 2011/11/28 22:50:45, nweiz wrote:
> At some point, this should probably warn to protect from typos.

Yeah, I'm not sure what the best path for this is. I consider linking to a type
to be bonus, so I'm OK with it failing to resolve a link and then just
defaulting to styling it a bit differently.

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:605: writeln(html);
On 2011/11/28 23:08:13, John Messerly wrote:
> as one line? writeln(md.markdownToHtml(comment));

Done.

http://codereview.chromium.org/8725007/diff/2001/utils/markdown/block_parser....
File utils/markdown/block_parser.dart (right):

http://codereview.chromium.org/8725007/diff/2001/utils/markdown/block_parser....
utils/markdown/block_parser.dart:119: List<String> parseChildLines(BlockParser
parser) {
On 2011/11/28 23:08:13, John Messerly wrote:
> heh :)

Oopsie!

http://codereview.chromium.org/8725007/diff/2001/utils/markdown/inline_parser...
File utils/markdown/inline_parser.dart (right):

http://codereview.chromium.org/8725007/diff/2001/utils/markdown/inline_parser...
utils/markdown/inline_parser.dart:103: writeTextRange(int start, int end) {
On 2011/11/28 22:50:45, nweiz wrote:
> Shadowing of start here is a little confusing.

Yeah, but I couldn't come up with a better name that didn't seem gratuitous.

http://codereview.chromium.org/8725007/diff/2001/utils/markdown/inline_parser...
utils/markdown/inline_parser.dart:294: if (link == null) {
On 2011/11/28 22:50:45, nweiz wrote:
> :(

This is actually part of markdown. Gruber hates us.

http://codereview.chromium.org/8725007/diff/2001/utils/markdown/lib.dart
File utils/markdown/lib.dart (right):

http://codereview.chromium.org/8725007/diff/2001/utils/markdown/lib.dart#newc...
utils/markdown/lib.dart:34: Node setImplicitLinkResolver(Node resolver(String
text)) {
On 2011/11/28 23:08:13, John Messerly wrote:
> what's the deal here? Is this a frog bug? (maybe a TODO if that's the case)

As in why didn't I just make it a field? Hmm. I didn't think about it.

[nweiz, 2011-11-29 19:57:19]

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart
File utils/dartdoc/dartdoc.dart (right):

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:493: if (name == null) return '';
On 2011/11/29 02:44:08, Bob Nystrom wrote:
> On 2011/11/28 22:50:45, nweiz wrote:
> > Why not return "_top" or something like that?
> 
> That could be an actual type name. An empty string actually works for now at
> least, but something better would be nice.

But an empty string won't actually provide an anchor for the top type. What
about "-top"? That's not a legal type name.

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:561: if (member != null) {
On 2011/11/29 02:44:08, Bob Nystrom wrote:
> On 2011/11/28 22:50:45, nweiz wrote:
> > if (member == null) continue;
> > 
> > Indentation is bad ;)
> 
> Continue in an if? ;)

Oh ha, I'm good at reading code.

http://codereview.chromium.org/8725007/diff/2001/utils/dartdoc/dartdoc.dart#n...
utils/dartdoc/dartdoc.dart:590: return new md.Element.text('code', name);
On 2011/11/29 02:44:08, Bob Nystrom wrote:
> On 2011/11/28 22:50:45, nweiz wrote:
> > At some point, this should probably warn to protect from typos.
> 
> Yeah, I'm not sure what the best path for this is. I consider linking to a
type
> to be bonus, so I'm OK with it failing to resolve a link and then just
> defaulting to styling it a bit differently.

It seems like you want it to be a warning to mitigate doc decay. Not only does
it help with typos, it also makes it easier to update docs after renaming or
removing a member. Since people will only use [] when they expect a link to be
generated, I think it makes sense to warn if it can't be.