doctest syntax

[omarkhan]

Hey this is very cool. I think it would be better if you change the doctest syntax from

###
Super square

Usage:

    square = require('square').square
    console.log(square(5))
    #36

Not only will it square 5 but it will square other numbers.

    console.log(square(4))
    #16
###
exports.square = (n) -> n * n

to something like this:

###
Super square

Usage:

    > square = require('square').square
    > square(5)
    36

Not only will it square 5 but it will square other numbers.

    > square(4)
    16
###
exports.square = (n) -> n * n

Why?

• More consistent with the coffeescript REPL.
• Dropping the calls to console.log() makes the doctests more readable.
• Sometimes you want to put something other than code in a <pre><code> block. Having each line of example code start with a > is an easy way for your parser to differentiate between code and other text.

[lmaccherone]

I started down that path but rejected it because in Python you can do this...

>>> def x():
...   return 'I am here'
... 
>>> x()
'I am here'
>>>

But in CoffeeScripts REPL, you have to hit ctrl-v to get multi-line behavior. Without it, you get this...

coffee> x = () ->
[Function]
coffee> 

And as others reported in the linked issue above, it doesn't seem to work on my Mac. Maybe I have a funky key mapping, but I got tired of mucking with it and changed gears. I didn't want to deviate from Python's doctest so much, but now that I have implemented it this way, I like it because:

• It now looks like code rather than an REPL session
• It also makes for easier cut-and-paste
• (as mentioned) multi-line REPL in CoffeeScript is unusable.

[omarkhan]

With the coffeescript REPL, you can get multiline behaviour by ending lines with a backspace:

coffee> f = (x) ->\
......>   return x*x

If you ditch the coffee and the ...... before the > you get something like this:

sqrt = (x) ->
  ###
  Return the square root of `x`.

      > square = (x) ->
      >   return x*x
      > sqrt square 4
      4
      > sqrt square 100
      100
  ###
  return Math.sqrt x

It's a silly example but I think it looks cleaner than having console.log() all over the place.

As for my last point, the coffeedoc documentation includes <pre><code> blocks that don't contain valid coffeescript code. I get this when I run coffeedoctest against the coffeedoc source:

Stderr exec'ing command 'coffee coffeedoctest_temp/home/omar/dev/coffeedoc/src/parsers_coffeedoctest.coffee'...
Error: In coffeedoctest_temp/home/omar/dev/coffeedoc/src/parsers_coffeedoctest.coffee, Parse error on line 29: Unexpected '...'
    at Object.parseError (/usr/lib/node_modules/coffee-script/lib/coffee-script/parser.js:470:11)
    at Object.parse (/usr/lib/node_modules/coffee-script/lib/coffee-script/parser.js:546:22)
    at /usr/lib/node_modules/coffee-script/lib/coffee-script/coffee-script.js:40:22
    at Object.run (/usr/lib/node_modules/coffee-script/lib/coffee-script/coffee-script.js:68:34)
    at /usr/lib/node_modules/coffee-script/lib/coffee-script/command.js:135:29
    at /usr/lib/node_modules/coffee-script/lib/coffee-script/command.js:110:18
    at [object Object].<anonymous> (fs.js:115:5)
    at [object Object].emit (events.js:64:17)
    at afterRead (fs.js:1111:12)
    at Object.wrapper [as oncomplete] (fs.js:254:17)

[lmaccherone]

You had to point that out. :-) Yeah, I need to fix that. That's a separate issue that I think I know what's wrong. I'll add an issue for that separately. It could use a bunch more testing. The coffeedoctest has no inline code/pre blocks in its headers so there is not much point running it on that so it's been low priority.

However, if you run `coffeedoctest --readme src, it chokes on the coffeedoctest README.md file because it's code/pre blocks. I need a way to escape some stuff from coffedoctest processing... or switch to a syntax like you are proposing. The thing I don't like the most about what you are proposing is that it's not true REPL session recording either. It's sorta between. The current syntax, at least, is real code... console.log() and all.

I think that when I clean up those few edge cases that I haven't tested (no code/pre blocks) and figure out how to escape stuff from processing, I'll prefer the current syntax. Any ideas on how to escape some stuff from processing while preserving the current syntax?