[PATCH] doc: Improve doxygen conversion

[Pekka Paalanen]

On Thu, 18 Dec 2014 20:15:04 -0800
Bill Spitzak <spitzak at gmail.com> wrote:

> The first patch supersedes one of my previous ones, the change is
> to remove some irrelevant and broken changes to the protocol docs.
> 
> Other changes fix the doxygen conversion so that each class/struct is
> a section, with all the related functions in that section. This makes
> it a lot easier to read the documentation.
> 

Hi,

I like the overall reorganization here.

Patch 4 adds some structs I'm not sure we should be documenting as
external API. Patch 5 seems to attempt to hide at least map_entry.

I'm not taking patch 5, because I believe that if we touch the
functions' docs, we should also document them completely, rather than
add some placeholders. Besides, the "Functions" lists is a nice place
to see what is not documented yet.

Patch 7 I would prefer to leave for later, for a series which actually
does improve the text.

So, I pushed patches 1-4, and 6.


Then, since it looks like the last time we have uploaded the generated
docs to the website was Oct 2013, I have generated and uploaded the
current bleeding edge version just now.

---

There is still something wrong with the parallel builds. If I do 'git
clean -dxf', followed by autogen, and then 'make -j4', I get:

make[3]: Leaving directory '/home/pq/git/wayland/doc/doxygen'
Making all in publican
make[3]: Entering directory '/home/pq/git/wayland/doc/publican'
  GEN      en-US
  GEN      en-US/images
  GEN      en-US/ProtocolInterfaces.xml
/bin/sh: en-US/ProtocolInterfaces.xml: No such file or directory
Makefile:528: recipe for target 'en-US/ProtocolInterfaces.xml' failed
make[3]: *** [en-US/ProtocolInterfaces.xml] Error 1
make[3]: *** Waiting for unfinished jobs....
  GEN      Wayland/en-US/html/css
make[3]: Leaving directory '/home/pq/git/wayland/doc/publican'
Makefile:353: recipe for target 'all-recursive' failed
make[2]: *** [all-recursive] Error 1
make[2]: Leaving directory '/home/pq/git/wayland/doc'
Makefile:1496: recipe for target 'all-recursive' failed
make[1]: *** [all-recursive] Error 1
make[1]: Leaving directory '/home/pq/git/wayland'
Makefile:866: recipe for target 'all' failed
make: *** [all] Error 2

A simple 'make' always works.


---

Now that we are no longer using Publican (apart from the name haunting
us in the Makefiles), would it be possible to get rid of the "move
these files temporarily away to generate something" rules in the
Makefiles?


Thanks,
pq