nginx undocumented directives

[Ruslan Ermilov]

Hi Gena,

On Thu, Dec 28, 2017 at 12:42:25PM +0200, Gena Makhomed wrote:
> Hello, All!
> 
> Scanning nginx sources and nginx documentation
> I found some directives, which present in nginx sources
> but absent in nginx documentation:

Internally, we have a document that explains why certain directives
are undocumented.

> acceptex_read
> iocp_threads
> post_acceptex
+ use iocp

These are undocumented b/c ngx_iocp_module is non-functional.

> devpoll_changes
> devpoll_events
> epoll_events
> eventport_events
> kqueue_changes
> kqueue_events
> gzip_hash
> gzip_no_buffer
> gzip_window
> postpone_gzipping
> http2_pool_size
> http2_streams_index_size

These are undocumented b/c we consider them "excessive configuraion".

> ssi_ignore_recycled_buffers

This used to be a hack for one big company, but isn't suitable for
general consumption.

> uwsgi_string

This is undocumented with the following notes: "no working examples,
no eval in recent uWSGI).  Sorry, but I don't remember what exactly
this means.  :)

> degradation
> degrade

This module needs more work.

> post_action

You already know the answer.

> smtp_client_buffer
> smtp_greeting_delay

There are no notes of why these aren't documented.

> post_action is known dangerous directive, it undocumented
> by purpose and in vim syntax file it marked accordingly:
> 
> syn keyword ngxDirectiveError contained post_action
> 
> But what about all rest undocumented directives, they are undocumented
> by purpose or through inadvertence, and may be in the near future
> all it (except post_action directive) will be documented?
> 
> And second question: how they are should be marked in nginx syntax file,
> as normal nginx directives, or color mark it as undocumented directives?
> 
> For example:
> 
> syn keyword ngxDirectiveUndocumented contained acceptex_read
> syn keyword ngxDirectiveUndocumented contained degradation
> ...
> syn keyword ngxDirectiveUndocumented contained uwsgi_string
> 
> hi link ngxDirectiveUndocumented Constant