XML documentation syntax, code generation and renaming lp_ functions to match parameter names.

Andrew Bartlett abartlet at samba.org
Sun Feb 2 16:47:12 MST 2014

On Mon, 2014-02-03 at 00:25 +0100, Michael Adam wrote:
> Hi Garming,
> On 2014-02-03 at 10:41 +1300, Garming Sam wrote:
> > 
> > >One other question about metadata:
> > >Could you provide a list of metadata entries that you
> > >added and their precise meaning?
> > >So far I saw "function", "synonym", "generated_function",
> > >"constant", "parm"
> > 
> > function corresponds to what function name is generated i.e. lp_xxxx
> > and lpcfg_xxxx. In the case where no name is specified, the
> > parameter name with underscores instead of spaces will be generated
> > automatically (unless it's marked not to generate).
> > 
> > generated_function = "0" if you don't want to generate an lp
> > function from this parameter. This is basically for special cases,
> > which may happen where there is some kind of conflict currently.
> > 
> > synonym is currently marked for any synonyms, but normal synonyms do
> > not usually have an xml page, so this only actually appears for
> > inverted synonyms currently. Currently marking a synonym means that
> > no lp function is also generated.
> > 
> > constant refers to whether or not the parameter should be constant,
> > but this is actually only currently used for strings. Constant in
> > this case indicates whether or not substitutions occur with the
> > string, I believe.

That is correct, and it also marks the return type of the C function as

> > parm, I was actually never entirely sure of. Some of the functions
> > are in the form FN_XX_PARM_XX and they take a different parameter,
> > share_params (instead of an integer which corresponds to the service
> > index). If anyone could shed light on it, that would be helpful.
> > There's not actually that many of them. And they look nearly
> > obsolete in the s4 macros.

Indeed, this is an odd case.  I've never been particularly clear if this
was something we were phasing in or out, or a partial rework of this
area.  Generally I prefer a service structure to a service number, but
we need to look into this and either finish or eliminate this. 

> > But yeah, with all this metadata stuff, it's previous obvious to see
> > which things were outliers.
> Thanks for the explanation!
> According to my pervious mail, I have prepared a first patchset for
> pushing. It does not add any function= occurrences except for those
> where the function starts with a "_". I.e those additions of
> function metadata that can be avoided by renaming variables and FN_
> definitions. A few of the original patches also added "parm" or
> "constant" metadata: I kept that portion of the original patches
> removing the function bit. One additional change is that I split
> the patch "docs: insert meta data into enable spoolss and
> writeable for marking a synonym" into two (keeping authorship etc).
> See this state in my master-param-reviewed branch:
> https://git.samba.org/?p=obnox/samba/samba-obnox.git;a=shortlog;h=master-param-reviewed
> If you are OK with that I'd push these and pursue the
> renaming of the functions+variables (and encourage you to
> join in. :-)

Thanks for your work and thoughts on this.  I agree, while we are
working to clean up this area, doing the other renames makes a lot of
sense, because it isn't likely to be tidied up later, so I fully support
doing it now. 


Andrew Bartlett

Andrew Bartlett
Authentication Developer, Samba Team  http://samba.org
Samba Developer, Catalyst IT          http://catalyst.net.nz/services/samba

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 819 bytes
Desc: This is a digitally signed message part
URL: <http://lists.samba.org/pipermail/samba-technical/attachments/20140203/0bf03edc/attachment.pgp>

More information about the samba-technical mailing list