"Try it now"

[spir]

On 04/14/2011 04:21 PM, Andrei Alexandrescu wrote:
> 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

Right. Sounds sensible.

Denis
-- 
_________________
vita es estrany
spir.wikidot.com