Docs

[Jim Jagielski <ji...@jaguNET.com>]

Right now I would say its pretty non-controversial that one of
the major stumbling blocks w/ more extensive usage of serf
is the lack of any documentation regarding it. Not even doxygen
pages can be found. This means that prospective users need
to dig thru subversion (the actual project, that is) to get
a feel on the best way to leverage serf, and I wonder how
many people/projects will actually go to all that much trouble...

Is there any intent to alleviate this? And external usage
guides that could be added to the website, etc...?

Personally, I'd like to see serf used a lot more in httpd,
but with a limited number of (active) httpd contributors
being familiar w/ serf, and non-existent documentation, it
is really hard to make that argument, esp since there are
other similar libs that don't "suffer" from those disadvantages.

Comments? Thoughts?

Re: Docs

[Jeff Kaufman <je...@google.com.INVALID>]

Another problem with lack of documentation is you end up with people
misusing Serf, sometimes in dangerous ways.  For example, PageSpeed
had CVE-2016-2092 [1] (fixed in [2]) because we had thought Serf was
checking that the certificate the domain supplied was valid for that
domain.

Jeff

[1] https://developers.google.com/speed/pagespeed/module/announce-sec-update-201601

[2] https://github.com/pagespeed/mod_pagespeed/commit/4af5e65 , which
is mostly plumbing around making our ssl_server_cert_callback call
X509_check_host.

On Tue, Feb 16, 2016 at 8:54 AM, Jim Jagielski <ji...@jagunet.com> wrote:
> Right now I would say its pretty non-controversial that one of
> the major stumbling blocks w/ more extensive usage of serf
> is the lack of any documentation regarding it. Not even doxygen
> pages can be found. This means that prospective users need
> to dig thru subversion (the actual project, that is) to get
> a feel on the best way to leverage serf, and I wonder how
> many people/projects will actually go to all that much trouble...
>
> Is there any intent to alleviate this? And external usage
> guides that could be added to the website, etc...?
>
> Personally, I'd like to see serf used a lot more in httpd,
> but with a limited number of (active) httpd contributors
> being familiar w/ serf, and non-existent documentation, it
> is really hard to make that argument, esp since there are
> other similar libs that don't "suffer" from those disadvantages.
>
> Comments? Thoughts?