Why nginx does not have an API reference manual

[agentzh]

Hi, list

People keep asking me (and others) why there is no API reference for
nginx internals. The answer is simple: it is still in flux and
changing even in nginx's stable releases.

For this reason, I won't work on such a reference and I bet Igor
Sysoev and Maxim Dounin will not either. (Feel free to prove me wrong!
:))

Nginx 0.8.54 changed the meaning of the return values of rewrite-phase
handlers, which makes Valery's guide to phases out of date even before
it was written:

    http://www.nginxguts.com/2011/01/phases/

See my comment at the bottom of that article.

This is not the only API change that is not backward compatible,
rather, just one in many others.

FWIW, the rewrite phase handlers do not even honor NGX_DONE nor
NGX_AGAIN in the version range of 0.8.42 ~ 0.8.53. My mail to this
list reporting this regression got completely ignored:

    http://forum.nginx.org/read.php?29,103078,103078

Is it funny? Sure not ;)

We've been adding more and more #if/#else craps to our modules's code
just in the hope of being compatible with more and more versions of
nginx. Let's count how many version checks in ngx_echo:

    $ ack '#if' src/|grep nginx_version|wc -l
   11

and that's the cost of making ngx_echo work with nginx 0.7.21 ~ 0.9.4.

And the number is similar for ngx_lua:

    $ ack '#if' src/|grep nginx_version|wc -l
    10

Well, one has to invest enough time on the nginx source and trace
*every* new releases carefully enough and prepare for API changes that
may make your module even fail to compile :) Most of the API changes
will not appear in the change log of the new nginx releases. Someone
(IIRC, it's Marcus Clyne) has requested a change log for nginx C API
in the list, but get ignored as always :)

Anyway, this email should not be taken as a complaint, rather, it is
just a report of the current status of nginx 3rd-party module/patch
development. Yeah, it's the reality. If this mail makes you feel the
other way around, I apologize for that.

We're currently maintaining dozens of nginx 3rd-party modules most of
which were born in the 0.8.x era. Just some of them have been
open-sourced. The maintenance work takes time, efforts and patience :)
But still we've been trying very hard to optimize this process for
fun, not only for maintaining existing modules but also for creating
brand new ones ;)

Hope you good luck!

-agentzh