"Try it now"

[spir]

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
-- 
_________________
vita es estrany
spir.wikidot.com