Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Doxygen: Misc ideas/proofs-of-concept #79
Over the last few months of using m.css I've been working on a 'post-process' script to do some further work on the generated html, and now it's polished enough that I figure you might appreciate it as a set of ideas or proofs-of-concept.
The example implementation (and output html) is here: achilles-doc.zip. The post-process script is
In no particular order:
Tags for inline namespaces
I know that Doxygen doesn't (currently) emit any sort of metadata indicating that a namespace is
Relevant parts of the proof-of-concept:
This is a very fine collection of very useful additions. Coincidentally I'm just about to publish a larger set of new features and improvements and some of these might be already partially solving a bunch of what you got here (in particular, the
Just give me some time to reply properly to all of the above :)
Argh! Of course I forgot to reply, sorry
Yes, definitely, I think this could go as an always-enabled feature, so no need for an option. I didn't have any inline namespace myself yet, that's probably the main reason this wasn't done yet. I hope this is easy to extract from the Doxygen XML files? TODOs for myself:
Do you know about Doxygen tag files? Those provide a way to link to external documentation (and to make this completely great, cppreference.com provides such a tag file). I'm using this quite heavily in the Magnum documentation, which links to external Corrade docs (a utility library) and also to STL -- see the Animation::TrackView class, for example:
I'm using a non-bold font for to distinguish the external references, experimented also with a different color but that turned out to be way too distracting.
I hope I ironed out most of the corner cases with
For the additional keywords, I can think of also stuff like new C++ attributes such as
Hmm. Doxygen actually has some pretty powerful preprocessor and I think it could be convinced to expand the
#define IMMOVABLE(TYPE) \ /** @brief Moving is not allowed */ \ TYPE(TYPE&&) = delete; \ /** @brief Moving is not allowed */ \ TYPE& operator=(TYPE&&) = delete; \ /** @brief Cop constructor */ \ TYPE(const TYPE&) = default; \ /** @brief Copy assignment */ \ TYPE& operator=(const TYPE&) = default;
(Disclaimer: I never tried this myself. Maybe it doesn't work at all.)
Another idea I'm thinking about is that it could be possible to detect what the function is (whether a copy/move constructor or a copy/move assignment) and then providing some implicit comment for it, in case it's defaulted/deleted. But knowing how bad the parser sometimes is (and thinking about the template-heavy cases), I'm not sure if it's at all possible to implement this robustly.
Hmm, I have to think about this a bit more. I have a similar case, need to integrate for example the following source code annotation, which adds colored rectangle next to custom RGB literals, but didn't find a way to do that cleanly yet without hardcoding stuff directly:
I think this should be done on the Python level, rather than on the resulting HTML (which is too late, in my opinion). There's a well-documented hierarchic structure coming out of the parser which is then fed to Jinja2 templates, so the hooks could be added there I think. Somehow. Don't have an idea how to do that yet.
RE inline namespaces: I had a cursory look through the doxygen XML, did a CTRL+F for 'inline', and didn't find anything relating to the namespaces. That's the extent of my investigation, though; there may have been some other indication that I missed...
RE external documentation links: I was aware of tag files, but thought the need to generate them was a bit of a non-starter. Using some provided by cppreference.com obviously solves that issue! One thing my approach does that I like is handles plurals etc correctly:
Does the tag file approach handle things like that? A minor detail, I suppose.
RE calling conventions and labels: Adding a configurable list of symbols sounds great. At some point over the weekend I'll regenerate our documentation with out the label-related post-processes and see if I can find any missing corner cases for you :)
RE defaults for rule-of-six: I had not even considered adding comments to the macros themselves, to be honest. I'll try that this weekend and see what happens.
Argh, that's what I feared. Could you try generating the stock HTML output and see if it's there at least? If yes, then it's just not propagated to XML (which would not surpise me at all). If not, then we would need to open a feature request and wait a year or so until it gets implemented, because no way in hell I'm touching their C++ parser. Nope.
Yes, that's what I meant, a new macro that gets recognized by m.css. I am doing a similar thing now, see here, but the
... is it a type
thanks in advance!
Guess I should have mentioned that I actually tried the stock HTML output first, didn't see any
Your recent version is almost perfect. The only edge cases my post-process catches now (ignoring the custom calling conventions) are functions that return
I tried adding comments to the macros as in your example, with
Feature request submitted: doxygen/doxygen#6741
Oh what the
<type>decltype(auto) constexpr</type> <definition>decltype(auto) constexpr Achilles::Coerce</definition>
I bet this will be the case for all other keywords when they go together with trailing return types.
EDIT: oh, actually, looking again, the
Oh, too bad. Then the only option would be a "is it a constructor" / "is it an
Well, good to hear that the labels thing seems a relatively straightforward thing to implemement.
As for the rest of it, I'm totally happy to keep building additional stuff on using a post-process, since
edit: come to think of it, that would be a better way of handling the inline namespaces thing too, really. If we assume that at some point between now and the heat death of the universe the doxygen team will inject
When I get back to this (later this week, right now I'm working on stuff that's not related to m.css), I'll have a look. The idea got a bit more stable in my head and I think the detection could be fairly doable. Ugly, but doable.
You mean doing that before they have the corresponding code integrated? I would have no way to write a test for this and things that are not tested tend to get broken.
Um, just realized, for the rule-of-six: as far as my experience goes, Doxygen always warns about undocumented functions unless it's a parameterless constructor or a destructor. So even if I implement some copy/move constructor/assignment detection on the m.css side, Doxygen will still warn about an undocumented function. Since (at least for me and a bunch of other users) the goal is to have a completely quiet output (and the script can't prevent Doxygen from complaining), I'm not sure if such a detection is worth implementing.