Re: [PATCH 2/6] Add doxygen comments for promptconfaction

[Jonathan Nieder <jrnieder@gmail.com>]

Hi Sean,

sean finney wrote:
> On Sun, Oct 25, 2009 at 03:50:44PM -0500, Jonathan Nieder wrote:

>> Will documentation processing tools choke on the string /*** used
>> elsewhere?  (Just curious.)
>
> in my experience doxygen is pretty robust in not treating documentation
> and/or formatting errors as fatal errors

Good.

>>> + * @param what Hints on what action should be taken by defualt.
>>
>> These contain not just hints but required information, right?
>
> you can document a function without defining the params/return, but
> doxygen will complain that the function documentation is incomplete.  so,
> not required but generally a good practice.  

Oh, sorry to be unclear.  I meant the bits of 'what'.  Looking more
closely now, it looks like 'what' contains the default action, plus
whether the conffile is new or has was deleted by the user.  So maybe:

@param what Bitfield with the current state of the conffile and
            action to be taken by default.

I was most interested in what value could be passed if the caller
doesn’t want a default, so:

            For example, cfof_prompt with no other bits set means
            "existing conffile changed, no default action".

But as I hinted before, I personally think it would be fine to leave
addressing this sort of nitpick to later (i.e., a separate patch, once
the code has settled down).  Your documentation here is already far
better than just about everywhere else in dpkg.

> gotta start somewhere right? 

Yes, much appreciated.

Many thanks,
Jonathan