[pacman-dev] [PATCH 0/4] fix Doxygen

[Jeremy Heiner]

My controversial topic for today is libalpm.3 and Doxygen (FS#9237).

It is time to completely throw out the idea of generating that page.

Who is going to 'man libalpm' and what would they hope to see?

The API reference Doxygen produces is useful when it lets you click
your way quickly to an answer: lots of narrowly focused pages with
lots of links. But if you wanted that would you 'man libalpm'? No.

Maybe some user guide stuff? But then Doxygen is not the right tool.

A couple of hits might come from people poking around /usr/lib and
wondering "WTF is this thing?". That would be rare (I hope), and yet
still Doxygen is not the right tool to answer that question.

So I just can't figure out a scenario starting with "I want help
making a front end to libalpm" that leads to a Doxygen generated
libalpm.3.

But Doxygen is still useful. It just needs a new purpose. Or at least
to be freed from the constraints of its current perceived purpose.

Here's what this patch set proposes:

Doxygen remains hidden behind a configure --enable (so most people
will never notice) but patch 1 completely changes what that --enable
does: forget libalpm.3, Doxygen now sees all the pacman code and
produces modern HTML.

Some of the markup that patch 1 added to Doxygen's INPUT was not
current, so patches 2&3 fix those issues.

And patch 4 deletes libalpm.3.txt, resolving FS#9237 in the most
brutal way possible. See: not controversial at all. :)

Happy solstice, everyone!

Jeremy Heiner (4):
  Remove DOXYGEN_MANS. New Doxyfile.in. Add 'make doxygen-*'.
  Clean up doxygen markup for the libalpm groups.
  Clean up doxygen @param warnings.
  Remove all references to libalpm.3

 configure.ac             |  26 +++-
 doc/.gitignore           |   3 +-
 doc/Doxyfile             | 305 -----------------------------------------------
 doc/Doxyfile.in          |  43 +++++++
 doc/Makefile.am          |  36 +++---
 doc/index.txt            |   1 -
 doc/libalpm.3.txt        |  39 ------
 doc/pacman.8.txt         |   4 +-
 doc/pacman.conf.5.txt    |   4 +-
 doc/vercmp.8.txt         |   2 +-
 lib/libalpm/alpm.c       |  11 --
 lib/libalpm/alpm.h       |  34 +++---
 lib/libalpm/alpm_list.c  |   7 +-
 lib/libalpm/alpm_list.h  |  36 +++++-
 lib/libalpm/be_local.c   |   2 +-
 lib/libalpm/be_package.c |   3 +-
 lib/libalpm/be_sync.c    |   1 -
 lib/libalpm/db.c         |   6 +-
 lib/libalpm/delta.c      |   7 --
 lib/libalpm/deps.c       |   4 +-
 lib/libalpm/dload.c      |   3 +-
 lib/libalpm/log.c        |   5 +-
 lib/libalpm/package.c    |   5 +-
 lib/libalpm/signing.c    |   3 +
 lib/libalpm/sync.c       |   2 +-
 lib/libalpm/trans.c      |   5 +-
 lib/libalpm/util.c       |   7 +-
 src/pacman/conf.c        |   1 -
 src/pacman/package.c     |   4 +-
 src/pacman/util.c        |   1 -
 30 files changed, 162 insertions(+), 448 deletions(-)
 delete mode 100644 doc/Doxyfile
 create mode 100644 doc/Doxyfile.in
 delete mode 100644 doc/libalpm.3.txt

-- 
1.8.5.2