Should this be done?  How?

I sent a pull request for the std.net.curl docs.  They all talk about assigning the results of web requests to strings, but at least on my setup this does not work (cannot assign char[] to string).  I was trying to walk someone else through using this and it was confusing.

 Error: cannot implicitly convert expression (get("http.dlang.org", AutoProtocol())) of type char[] to string

BTW I don't know why you can't convert a char[] to string - seems harmless enough conversion that way around.

Pull request here (I haven't had time to check properly).

https://github.com/D-Programming-Language/phobos/pull/3564

On 08/20/2015 01:41 AM, Laeeth Isharc wrote:
>
> BTW I don't know why you can't convert a char[] to string - seems
> harmless enough conversion that way around.

It would need to allocate a new string, otherwise, one would be able to modify the contents of the immutable string via the char[] reference.

On Thursday, 20 August 2015 at 00:00:55 UTC, Timon Gehr wrote:
> On 08/20/2015 01:41 AM, Laeeth Isharc wrote:
>>
>> BTW I don't know why you can't convert a char[] to string - seems
>> harmless enough conversion that way around.
>
> It would need to allocate a new string, otherwise, one would be able to modify the contents of the immutable string via the char[] reference.

and you don't want sneaky allocations creeping in.  ok.  tku.

how about automatically checking code in examples?

On 08/20/2015 02:02 AM, Laeeth Isharc wrote:
> On Thursday, 20 August 2015 at 00:00:55 UTC, Timon Gehr wrote:
>> On 08/20/2015 01:41 AM, Laeeth Isharc wrote:
>>>
>>> BTW I don't know why you can't convert a char[] to string - seems
>>> harmless enough conversion that way around.
>>
>> It would need to allocate a new string, otherwise, one would be able
>> to modify the contents of the immutable string via the char[] reference.
>
> and you don't want sneaky allocations creeping in.  ok.  tku.
>
> how about automatically checking code in examples?

I think this is the recommended mechanism for that: http://dlang.org/unittest.html (documented unit tests)

On Thursday, August 20, 2015 02:09:12 Timon Gehr via Digitalmars-d-learn wrote:
> On 08/20/2015 02:02 AM, Laeeth Isharc wrote:
> > On Thursday, 20 August 2015 at 00:00:55 UTC, Timon Gehr wrote:
> >> On 08/20/2015 01:41 AM, Laeeth Isharc wrote:
> >>>
> >>> BTW I don't know why you can't convert a char[] to string - seems harmless enough conversion that way around.
> >>
> >> It would need to allocate a new string, otherwise, one would be able
> >> to modify the contents of the immutable string via the char[] reference.
> >
> > and you don't want sneaky allocations creeping in.  ok.  tku.
> >
> > how about automatically checking code in examples?
>
> I think this is the recommended mechanism for that: http://dlang.org/unittest.html (documented unit tests)

In general, the code examples are supposed to be unit tests with an empty ddoc comment on them so that they're unit tested. However, in the case of std.net.curl, because it would be contacting websites, I doubt that they're going to be turned into ddoc-ed unit tests.

- Jonathna M Davis

On Thursday, 20 August 2015 at 01:56:31 UTC, Jonathan M Davis

> In general, the code examples are supposed to be unit tests with an empty ddoc comment on them so that they're unit tested. However, in the case of std.net.curl, because it would be contacting websites, I doubt that they're going to be turned into ddoc-ed unit tests.
>
> - Jonathna M Davis

unittest could start a local server, but I guess more trouble than it's worth.

On 2015-08-20 01:41, Laeeth Isharc wrote:
> Should this be done?  How?

Just use a documented unit tests block:

///
unittest
{
    // code goes here
}

It will be run as part of the unit tests and it will be included when generating the documentation.

Although I don't have a good solution for the code in dlang.org that's not part of the Phobos/druntime documentation.

> I sent a pull request for the std.net.curl docs.  They all talk about
> assigning the results of web requests to strings, but at least on my
> setup this does not work (cannot assign char[] to string).  I was trying
> to walk someone else through using this and it was confusing.
>
>   Error: cannot implicitly convert expression (get("http.dlang.org",
> AutoProtocol())) of type char[] to string
>
> BTW I don't know why you can't convert a char[] to string - seems
> harmless enough conversion that way around.

char[] is mutable while string is not. Someone else can have a reference to the same data and change it will it's typed as "string", breaking the type system.

-- 
/Jacob Carlborg

On Thursday, 20 August 2015 at 06:28:44 UTC, Jacob Carlborg wrote:
> On 2015-08-20 01:41, Laeeth Isharc wrote:
>> [...]
>
> Just use a documented unit tests block:
>
> ///
> unittest
> {
>     // code goes here
> }
>
> It will be run as part of the unit tests and it will be included when generating the documentation.
>
> Although I don't have a good solution for the code in dlang.org that's not part of the Phobos/druntime documentation.
>
>> [...]
>
> char[] is mutable while string is not. Someone else can have a reference to the same data and change it will it's typed as "string", breaking the type system.

Will AutoProtocol().idup not make this work?
Make an immutable copy of whatever AutoProtocol() returns, which should be then immutable char[] (i.e. string)

On 2015-08-20 10:49, wobbles wrote:

> Will AutoProtocol().idup not make this work?
> Make an immutable copy of whatever AutoProtocol() returns, which should
> be then immutable char[] (i.e. string)

Yes, that should work.

-- 
/Jacob Carlborg

On Thursday, 20 August 2015 at 06:28:44 UTC, Jacob Carlborg wrote:
> On 2015-08-20 01:41, Laeeth Isharc wrote:
>> Should this be done?  How?
>
> Just use a documented unit tests block:
>
> ///
> unittest
> {
>     // code goes here
> }
>
> It will be run as part of the unit tests and it will be included when generating the documentation.
>
> Although I don't have a good solution for the code in dlang.org that's not part of the Phobos/druntime documentation.

It think it would be a positive for dlang.org's code to be unit tested, but it might also be tricky if that were the only option for including code in dlang.org.

For instance, suppose the dlang.org page looks something like
text
code block
text
code block that depends on above code block

I actually see this rather often. If you change the code blocks to unit tests, then the second code block would not compile by itself. I see two options: 1) make one big unit test and have the second piece of text be a comment in it, 2) include the original unit test in the second code block (messy and has its own set of problems).

Maybe there is a solution to this, but I think it would require some sort of change. Maybe one solution is to improve the way text comments can be used with unit tests. Alternately, it might be interesting to have a way to refer/import other unit tests.