On Mon, 16 Jun 2014, Dima Tisnek wrote:

> basic docs, like curl_easy_setopt are great.
> demanding features, e.g. multi interface, are shot.

What about it isn't documented good enough or is confusing?

> furthermore I suspect libcurl users who talk to the library in C are a
> minority compared to python, php, etc.

Oh right. I bet a certain amount of users think about their version of "curl"
when I ask about curl and libcurl documentation and I can only agree that a
lot of the bindings are very sparesly documented - sometimes not at all.

> documentation for high level languages is left out of scope.

Sometimes it hurts our users that we do libcurl in one project and the
bindings are separate projects written and handled by separate people, but I
also can't think of any other way to do it. I also believe it benefits the
bindings to not be closely assiciated or tide to the curl project as it leaves
them the total freedom to act in their own interest.

> admittedly php.net wiki-style docs are actually quite useful. on the other
> hand, whenever I code in Python, I have to look up libcurl docs and mentally
> translate interface into my data types. I'm quite used to it, it works
> pretty well. A novice would be lost for sure.

But is that anything we even _can fix within the curl project? If so, how?
What can we do to help the bindings projects to provide better docs?

> I think it's best summarised that there ought to be two kinds of
> documentation corresponding to two user classes:
> * libcurl and interface developers
> * libcurl/pycurl/php/*/command line end users

I don't understand the separation here. What are the "interface developers" ?
Are they the authors of bindings?

-- 
  / daniel.haxx.se
-------------------------------------------------------------------
List admin: http://cool.haxx.se/list/listinfo/curl-library
Etiquette:  http://curl.haxx.se/mail/etiquette.html