What kind of documentation? This is a little ambiguous.
The code should be obviously written to be readable and documented according to the style popular with given language -- this usually means comments or equivalent mechanism.

Should the documentation include a mathematical proof of correctness of the program?

A dissertation about the program's design and design decisions made?

Installation instructions?

-- RadomirDopieralski, 2007-Nov-21

Yes.

-- [[YvesPiguet]], 2007-Nov-21

"Yes" as in "all of the above"? This is quite a lot of work.

-- RadomirDopieralski, 2007-Nov-21

Yes, we should have some common sense here. A reference implementation should be easy to use and easy to grasp, be it with a good interface, clear code, good comments, good usage examples and/or good external documentation.

A mathematical proof of correctness would be difficult with the lack of precision of Creole 1.0.

-- [[YvesPiguet]], 2007-Nov-21

As I see it, a reference implementation would only have to output a DOM tree in some form (XML?), so that it could be compared with the output of the application I'm developing and want to test. It doesn't need to be fast or efficient, but it would be nice if it had a lot of options in all those parts where the spec allows flexibility. I'm not sure whether I care about how clear the source code is or what language it is written in, as long as I can run it from my unit tests.

A perfect solution would be a "validator", that would take Creole and parsed HTML as input, and find parsing errors. I'm not sure whether it's even possible, but that would be the "reference implementation" of my dreams.

-- RadomirDopieralski, 2007-Nov-28