On Mon, Aug 25, 2014 at 09:27:17PM +0100, Thomas Adam wrote: > On Mon, Aug 25, 2014 at 04:19:37PM -0400, Dan Espen wrote: > > Very sorry you still don't like the XML format. > > I find it clumsy, but I'm willing to put up with it. > > Personally I almost always go online and read Fvwm man pages > > as HTML. Anything we can come up with that renders HTML > > is good with me. > > That's definitely an output format we'll be doing, even with mdoc---to > lose that would be irritating to say the least. > > > I want to mention, when I wrote F_CMD_ARGS, > > one of the things I had in mind was to put function > > documentation in the .c files. I envisioned some kind of > > extract run generating the actual man page input. > > I was trying to make the functions easy to find by giving > > them a uniform appearance. > > Interesting. Whilst I don't like macros in place of formal function > arguments myself, I can see why you did this, Dan.
Well, for me the macros F_CMD_ARGS and F_PASS_ARGS helped me a lot, even without documnetation. Before we had them, you had to change more than 300 funtion declarations and function headers and maybe 1000 argument lists in internal calls when you added or removed a command argument. Now, I could add in another command argument and had to change only a couple of calls that are too specific to use F_PASS_ARGS. They have saved me many, many hours of boring, tedious and error prone work and have definitely improved the overall code quality. Apart from that, I'm not a big fan of macros that contain more than a constant or a very simple expressions. But sometimes they can really help. > On the point about > documentation, this is precisely what doxygen allows for. We could > always make use of that---and certainly it would be an interesting > excerise to do, as it would help appraise and justify the existing > functions we have, and help identify any potential cleanups, etc. I've worked with Doxygen on several occations but never got fond of it. People forget to update the source code documentation, and summaries of whole modules are hardly ever written. Often you end up with a loose collection of poorly maintained function descriptions without the correllations documented. Personally I find it easier to remember writing decent documentation when it's all in a single place (one of my main woes with the xml files). Ciao Dominik ^_^ ^_^ -- Dominik Vogt
