On 10.10.2019 20:30, Lars Kurth wrote: > On 10/10/2019, 18:05, "Andrew Cooper" <andrew.coop...@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 Xenemail@example.com https://lists.xenproject.org/mailman/listinfo/xen-devel