Modify apidoc to prefer handwritten HTML5 docs over those in MDN or generated code.

Modify apidoc to prefer handwritten HTML5 docs over those in MDN or generated code.

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

[Bob Nystrom, 2012-06-11 19:31:19]

A couple of minor issues. It's hackish, but works. When dartdoc moves to
dart2js, I hope we can do a cleaner solution.

Assuming the make the suggested changes, LGTM.

https://chromiumcodereview.appspot.com/10540085/diff/1/utils/apidoc/apidoc.dart
File utils/apidoc/apidoc.dart (right):

https://chromiumcodereview.appspot.com/10540085/diff/1/utils/apidoc/apidoc.da...
utils/apidoc/apidoc.dart:113: htmldoc.document();
This still generates the output files, doesn't it? That will waste a decent
amount of time.

The easiest hack to fix this will be to override endFile(), write(), and
writeln() in Htmldoc to have them do nothing.

https://chromiumcodereview.appspot.com/10540085/diff/1/utils/apidoc/apidoc.da...
utils/apidoc/apidoc.dart:144: * HTML library.
Hackish, but works.

I would leave a comment explaining that it works this way because frog is
relying on global internal state.

https://chromiumcodereview.appspot.com/10540085/diff/1/utils/apidoc/apidoc.da...
utils/apidoc/apidoc.dart:400: // Prefer hand-written Dart comments over stuff
from MDN.
This comment is confusing now. How about changing the params too:

mdnComment, generatedComment, handWrittenComment

And then remove this comment?

[vsm, 2012-06-11 20:51:01]

thanks, landing

https://chromiumcodereview.appspot.com/10540085/diff/1/utils/apidoc/apidoc.dart
File utils/apidoc/apidoc.dart (right):

https://chromiumcodereview.appspot.com/10540085/diff/1/utils/apidoc/apidoc.da...
utils/apidoc/apidoc.dart:113: htmldoc.document();
Thanks - done.

On 2012/06/11 19:31:19, Bob Nystrom wrote:
> This still generates the output files, doesn't it? That will waste a decent
> amount of time.
> 
> The easiest hack to fix this will be to override endFile(), write(), and
> writeln() in Htmldoc to have them do nothing.

https://chromiumcodereview.appspot.com/10540085/diff/1/utils/apidoc/apidoc.da...
utils/apidoc/apidoc.dart:144: * HTML library.
Comment added at the reset above.

On 2012/06/11 19:31:19, Bob Nystrom wrote:
> Hackish, but works.
> 
> I would leave a comment explaining that it works this way because frog is
> relying on global internal state.

https://chromiumcodereview.appspot.com/10540085/diff/1/utils/apidoc/apidoc.da...
utils/apidoc/apidoc.dart:400: // Prefer hand-written Dart comments over stuff
from MDN.
Done.  I used "fileComment" instead of "generatedComment" (and added some
explanation) as not all files are generated.

On 2012/06/11 19:31:19, Bob Nystrom wrote:
> This comment is confusing now. How about changing the params too:
> 
> mdnComment, generatedComment, handWrittenComment
> 
> And then remove this comment?