On 10/11/11 01.24, Walter Bright wrote:
On 11/9/2011 12:53 PM, Jonas Drewsen wrote:
Before sending it for official review again I would really like some
comments on
the new API and if you think it is better or worse etc.
http://freeze.steamwinter.com/D/web/phobos/etc_curl.html
Thank you so much for doing this. I think it's a nice piece of work.
Thank you.
It seems that people like this API better. I'll head on to implement the
last common HTTP request types (head() etc.), polish and fix the stuff
you've mentioned below then.
/Jonas
Some nitpicky comments:
* libcurl should be a link to where people can read up on what it is.
I suggest http://curl.haxx.se/libcurl
Point out that the user will need libcurl installed on their system in
order to use etc.curl.
* Need a brief statement on why a D programmer should prefer using
etc.curl rather than directly use libcurl.
* "ranges" should be a link to what a range is
* examples should include
import etc.curl;
and any other needed, like std.stdio. In fact, they should be cut &
paste complete examples that are compilable and runnable.
* Keep comment lines under 40 characters; use multiple lines for longer
comments. (This is so things format better for small screens.) Try to
format code so it doesn't need more than 40 lines. I tend to indent by
only two spaces in documentation which helps.
* Remove all instances of the word "you". For example,
"If you need more control than the low high level functions provide,
you'll have to use the low level API:"
rewrite as:
"For more control than the low high level functions provide, use the low
level API:"
Note how much simpler and direct it is. "You" is almost always an
unnecessary filler word, and frankly has no place in a reference work.
* For the same reason, get rid of "we":
"First, we create an instance" => "First, create an instance"
"We then set" => "Then set"
* derivate => derived
* "Connection type used when the url should be used to auto detect
protocol"
.. I have no idea what this sentence means.
* "HTTP/FTP upload from local file system." => Upload file from local
file system using the HTTP or FTP protocol."
And which protocol would be used?
* "A string with the content of the resource pointer to by the url"
Missing period. Grammar problems, how about:
"A string containing the content of the resource pointed to by the url."
Most of these apply to the rest of the documentation.
Also, need more examples.
I tend to like references to things in other modules to be hyperlinks.
For example, writeln should be $(LINK2
http://www.d-programming-language.org/phobos/std_stdio.html#writeln,
writeln)
