Re: [Qemu-devel] [PATCH v2 1/5] fw_cfg: document fw_cfg_modify_iXX() update functions

[Peter Maydell]

On 1 September 2015 at 18:45, Gabriel L. Somlo <address@hidden> wrote:
> On Tue, Sep 01, 2015 at 06:33:25PM +0100, Peter Maydell wrote:
>> This doesn't cover fw_cfg_modify_file(); is that intentional?
>
> There should already be a paragraph in there (further down from where
> this is supposed to go in) describing fw_cfg_modify_file(), which
> isn't affected by this.

Sorry, so there is.

>> As an aside, shouldn't this function-level documentation be done
>> via doc-comments in the header file where the prototypes are
>> declared? (You don't need to move the docs around in this series,
>> but it might be nice to do at some point.)
>
> You mean, leave docs/specs/fw_cfg.txt to deal with the guest-side
> port/mmio api only, and have the host-side functions simply documented
> as comments in include/hw/nvram/fw_cfg.h ?
>
> That should be relatively painless, if that's the agreed-upon
> convention...

Yes. I think at the point this file was written we probably hadn't
started using doc-comments for our APIs. (My usual place to crib
the formatting for doc-comments is the extract/deposit APIs in
bitops.h.)

thanks
-- PMM