XML documentation syntax, code generation and renaming lp_ functions to match parameter names.
garming at catalyst.net.nz
Sun Feb 2 17:11:16 MST 2014
On 03/02/14 12:47, Andrew Bartlett wrote:
> 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:
>> 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
Just been looking into the existence of 'parm'. It came with a sync
trunk, so we can't really track it any further than some time in 2006.
share_params seems to be simply a struct with just an int inside.
Whether this was an attempt to simply switch it out or for efficiency
reasons, we can't really be sure.
We can probably work together to try to get rid of it in some manner.
More information about the samba-technical