www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.learn - automatically verifying code samples in phobos docs

reply "Laeeth Isharc" <laeethnospam nospamlaeeth.com> writes:
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
Aug 19 2015
next sibling parent reply Timon Gehr <timon.gehr gmx.ch> writes:
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.
Aug 19 2015
parent reply "Laeeth Isharc" <laeethnospam nospamlaeeth.com> writes:
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?
Aug 19 2015
parent reply Timon Gehr <timon.gehr gmx.ch> writes:
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)
Aug 19 2015
parent reply Jonathan M Davis via Digitalmars-d-learn writes:
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
Aug 19 2015
parent "Laeeth Isharc" <spamnolaeeth nospamlaeeth.com> writes:
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.
Aug 19 2015
prev sibling parent reply Jacob Carlborg <doob me.com> writes:
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
Aug 19 2015
next sibling parent reply "wobbles" <grogan.colin gmail.com> writes:
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)
Aug 20 2015
parent Jacob Carlborg <doob me.com> writes:
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
Aug 20 2015
prev sibling parent "jmh530" <john.michael.hall gmail.com> writes:
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.
Aug 20 2015