[RFC wayland] doc: generate doxygen html output from the scanner

[Tiago Vignatti]

On 11/04/2015 09:44 PM, Peter Hutterer wrote:
> On Wed, Nov 04, 2015 at 03:30:29PM -0800, Bryce Harrington wrote:
>> On Mon, Nov 02, 2015 at 10:27:54AM +1000, Peter Hutterer wrote:
>>> On Fri, Oct 30, 2015 at 03:40:33PM -0700, Bryce Harrington wrote:
>>> but: the current API docs in publican are useless. look at appendix B, the
>>> "client API". http://wayland.freedesktop.org/docs/html/apb.html
>>> it's technically the client API but it's lacking anything that's not core
>>> libwayland API. it doesn't describe protocol interfaces at all. That's only
>>> in the protocol spec (Appendix A) and that is generated straight from the
>>> xml without doxygen's involvement.
>>>
>>> The doxygen output in this patch only does the protocol interfaces. so there
>>> isn't even an overlap between these new ones and the current ones, but the
>>> new ones could be made to include the core libwayland bits too.
>>
>> Yeah I agree, and that's a good point.  I wouldn't be at all opposed to
>> dropping this.  If we can do that as a follow up patch, then it'd make
>> it easier to get wider visibility on the change, in case anyone has
>> reservations about it.
>>
>> Do you know why the API docs were added to the publican doc in the first
>> place?  Was it simply to make sure the docs existed somewhere, or was
>> there a specific need e.g. like being able to have them in a more easily
>> printed format?  Or...?
>
> the publican doc was the one doc source, both for the PDF and the website.
> I suspect Tiago's intent (e2db4cf) was simply to add more useful stuff to
> it, at the cost of a doxygen run and an xsl transformation.
> And it works, the server/client library both are there and documented, we're
> just missing the actual protocol bits :)

right on!

Tiago