Re: [Xen-devel] [RFC] Documentation formats, licenses and file system structure

[Jan Beulich <jbeulich@suse.com>]

On 10.10.2019 20:30, Lars Kurth wrote:
> On 10/10/2019, 18:05, "Andrew Cooper" <Andrew.Cooper3@citrix.com> wrote:
>     On 10/10/2019 13:34, Lars Kurth wrote:
>     > Existing formats and licenses
>     > * Hypercall ABI Documentation generated from Xen public headers
>     > Format: kerndoc
>     > License: typically BSD-3-Clause (documentation is generated from public headers)
>     
>     Its homegrown markup&perl, superimposed on what used to be doxygen in
>     the past.
> 
> Oh, I forgot
>     
>     I wasn't planning on reusing any of the markup, and wasn't expecting to
>     use much of the text either.  I'm still considering the option of
>     defining that xen/public/* isn't the canonical description of the ABI,
>     because C is the wrong tool for the job.
>     
>     Its fine to provide a C set of headers implementing an ABI, but there is
>     a very deliberate reason why the canonical migration v2 spec is in a
>     text document.
> 
> @Stefano: as you and I believe Brian will be spending time on improving the
> ABI docs, I think we need to build some agreement here on what/how
> to do it. I was assuming that generally the consensus was to have
> docs close to the code in source, but this does not seem to be the case.

Well, for migration v2 having the spec in a text file seems sensible
to me. For the public ABI, however, I think it's more helpful to have
the doc next to the actual definitions. Considering the possible use
of languages other than C I can certainly see why separating both
would be even more clean, but I think here we want to weigh practical
purposes against cleanliness.

Jan

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xenproject.org
https://lists.xenproject.org/mailman/listinfo/xen-devel