digitalmars.D.learn - most ddoc examples not runnable; Edit is buggy; DDOC generates wrong
- timotheecour (43/43) Mar 12 2013 Is there any short term plan to make examples in ddoc runnable?
Is there any short term plan to make examples in ddoc runnable? right now, the only one that runs is the one on the home page dlang.org. Example: in http://dlang.org/phobos/std_path.html: the 1st code sample (under baseName) when you click on run: /home/c318/c110.d(2): Error: Declaration expected, not 'assert' when you click on Edit and wrap the code sample in this: ---- import std.path; void main(){ ... } ---- now it runs fine. I propose: A) the examples should be runnable by default (at least a majority of them, in the meantime) B) we can do this either by requesting user code to write runnable examples (would require a lot of changes in documentation, maybe not so good and verbose), or by implicitly wrapping each example inside a main function, with proper import declarations (ala rdmd --eval, which imports all phobos). That may be overkill and produce name clashes (std.file.write,std.stdio.write,..). Maybe just import current module implicitly, all else requires the user to explicitly import. C) to keep examples in sync (I just made a pull request that fixes a wrong syntax in std.random), there should be an autotester that does just that, at least verifying stuff compiles, if not runs without breaking asserts. D) will that be obsoleted by unittests appearing in ddoc? E) right now Edit button in those examples is buggy: try clicking on Edit in second example box in baseName's example: the code is replaced by something different from example above. F) The DDOC generates extraneous "Example:" tag in almost all cases (see for example in dirName: you have Examples: ... (ok) and then Exampe: (empty)
Mar 12 2013