reminder: undocumented options not allowed

[Karolin Seeger]

On Thu, Oct 10, 2013 at 07:56:27PM +1300, Andrew Bartlett wrote:
> On Wed, 2013-10-09 at 09:48 +0200, Björn JACKE wrote:
> > Hi,
> > 
> > after I just saw that we have a very usefull parameter
> > 
> > spoolss: architecture = ...
> > 
> > that not even most of the developers know about, I want to remind that we
> > discussed and decided the policy that ALL new options (parametric or not) have
> > to be documented in the man pages.
> > 
> > Also if there is not a reason to make an option parametric (like for vfs
> > modules) then the option should be a real option, that is also printed out by
> > testparm -v.
> > 
> > As a result of that policy, a review+ should NOT be granted if the
> > corresponding man page entry is not added at the same time.
> 
> I don't remember this discussion, but originally the distinction between
> these 'parametric' options and real options (aside from vfs modules) was
> to enable tweaks to be inserted into points in the code, that would not
> be first-class options, and should not be presented to users.  
> 
> I certainly agree that some parametric options should in retrospect have
> been real options, but if we remove the distinction, how should
> developer-only tweaks be done?

The problem is that developers add parametric options, because they don't
need to add documentation then. Or they can add them in the middle of a
maintenance release cycle.

There are parametric options that are documented and I think there are
also real parameters that are developer tweaks. Btw, please define
developers tweaks... ;-)

>From my point of view, even developer tweaks could be documented with
comments like "use with care" or "developer tweak". Even developers use
documentation sometimes...

I do really hate parametric options.

Cheers,
Karo

-- 
Samba			http://www.samba.org
SerNet			http://www.sernet.de
sambaXP			http://www.sambaxp.org