"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