Re: "Try it now"

[Andrei Alexandrescu]

On 4/14/11 6:49 AM, spir wrote:
On 04/14/2011 11:30 AM, Jacob Carlborg wrote:
On 2011-04-13 22:38, Andrei Alexandrescu wrote:
I'm quite excited about the new look of std (right now realized only by
http://d-programming-language.org/phobos-prerelease/std_algorithm.html).
Here's a suggestion on how we could improve it more.
Adam wrote an in-browser evaluator for D programs. These, when presented
on the homepage with "hello, world" in them are of limited usefulness.
However, a personalized "try it now" button present for _each_ artifact
in an std module would be of great usefulness.

When I try some html or javascript I find it very useful to go to one of
those sites that allow me to try some code right then and there. The key
aspect is that the code edit field is already filled with code that is
close to what I'm looking for, which I can then edit and try until it
does what I want.

Similarly, it would be great if next to e.g.
http://d-programming-language.org/phobos-prerelease/std_algorithm.html#setUnion

there would be a "Try it now" button. Clicking on that button would open
an overlay with an edit window. The edit window initially contains the
example text:

unittest
{
int[] a = [ 1, 2, 4, 5, 7, 9 ];
int[] b = [ 0, 1, 2, 4, 7, 8 ];
int[] c = [ 10 ];
assert(setUnion(a, b).length == a.length + b.length);
assert(equal(setUnion(a, b), [0, 1, 1, 2, 2, 4, 4, 5, 7, 7, 8, 9][]));
assert(equal(setUnion(a, c, b), [0, 1, 1, 2, 2, 4, 4, 5, 7, 7, 8, 9,
10][]));
}

Then the user can change, compile, and run that program, to ultimately
close the overlay and return to the documentation.

What do you think? This would require some work in the compiler (make
unittests documentable, make their text available to ddoc macros) and
some work in the front end. I hope this catches the fancy of e.g.
Walter/Don and Adam.


Andrei

This is looking better and better each time. One thing I still don't
like is
the cheat sheet, I think it looks cluttered. I think it's just too
much text in
most of the rows.

Agreed. May I suggest an easy (and imo sensible) doc guideline, which
would also allow automatising cheat sheet generation?

1. The top line of each doc block defines the *purpose* of the given
piece of code
(meaning for a func either what value it computes, or what action it
performs).
2. This line is taken as is by a cheat sheet generator.

Examples:

PI
/** The value of pi.
... */

struct Circle
/** Representation of a circle, as defined by radius & position of center.
... */

size_t indexOf (E elem) // method of some collection type
/** Index of first occurrence of elem in collection --else throws
IndexError.
... */

void_t erase (E elem) // ditto
/** Erase all occurrences of elem in collection.
... */

Denis

I prefer the cheat sheet contain code snippets. They are very terse and 
eloquent.

Andrei