C++: documented symbols in namespaces are ignored

[stephanlachnit]

Any documented symbols in a namespace are currently ignored. This is probably a known bug.

To reproduce, create this test.hpp:

namespace A {
/**
 * Test
 *
 * @param a a
 * @return a
*/
int test(int a) { return a; }
}

Here hawkmoth --domain cpp test.hpp shows no output. However, removing the namespace results in the correct documentation.

[BrunoMSantos]

@stephanlachnit thanks for the report. This is a known limitation indeed, we are currently not recursing into namespaces nor keeping track of them. That's probably the most limiting issue with C++ support in fact.

There are some improvements in the parser code that we are aiming for before we tackle additional C++ functionality though. Most recently, #206 is a draft proposal on how to make (some of) those improvements (related issue: #180).

[stephanlachnit]

@BrunoMSantos thanks for the swift reply! I'm wondering if it is possible to just "ignore" the namespaces, meaning that the smybols will be read but the namespace ignored. In the project I'm investigating to use hawkmoth we only ever have one namespace per header file, so it wouldn't much of an issue to put this in the docs otherwise.

The alternative would be to add #ifndef HAWKMOTH_DOCS guards around the namespaces, but that's kinda ugly...

[BrunoMSantos]

Yeah, that workaround on our end would be just as ugly honestly and it would be specific to your use case. Personally I'd rather focus on fixing it for real and, for the record, knowing someone's actually interested is a good motivator :P

What are your timelines? I'd be happy to use your project as a driving force for C++ support if you can bear with our spare time development. I don't code in C++ if I can avoid it, so I have no personal use for C++ support.

[stephanlachnit]

Yeah, that workaround on our end would be just as ugly honestly and it would be specific to your use case. Personally I'd rather focus on fixing it for real and, for the record, knowing someone's actually interested is a good motivator :P

Fair, if that is equally ugly then there is no point. I can try to look into the code a bit and see what I can do, if I find the time.

What are your timelines? I'd be happy to use your project as a driving force for C++ support if you can bear with our spare time development. I don't code in C++ if I can avoid it, so I have no personal use for C++ support.

We just started fortunately, however we are at a point where we want to start documentation of the classes as our codebase starts to grow. So having a pretty website isn't important right now, as we can already start adding the documentation anyway. I'm looking to different options right now, and hawkmoth seems much nicer than Doxygen+Breathe.

Generally speaking, from everything I tested the only thing I'm missing is namespaces. Concept would be nice eventually but are not that important right now.

[BrunoMSantos]

Yeah, that workaround on our end would be just as ugly honestly and it would be specific to your use case. Personally I'd rather focus on fixing it for real and, for the record, knowing someone's actually interested is a good motivator :P

Fair, if that is equally ugly then there is no point. I can try to look into the code a bit and see what I can do, if I find the time.

Not sure using the #ifndef on your side would work actually. It may lead to Clang errors if (e.g.) you have multiple symbols that would then alias each other if the namespaces are occluded :/

What are your timelines? I'd be happy to use your project as a driving force for C++ support if you can bear with our spare time development. I don't code in C++ if I can avoid it, so I have no personal use for C++ support.

We just started fortunately, however we are at a point where we want to start documentation of the classes as our codebase starts to grow. So having a pretty website isn't important right now, as we can already start adding the documentation anyway.

Well, that will be a decision for you guys, but that would indeed buy us time. And if you're using javadoc syntax you probably won't loose too much if you then need to back-pedal a bit either...

Is this project open source by the way?

I'm looking to different options right now, and hawkmoth seems much nicer than Doxygen+Breathe.

❤️

Generally speaking, from everything I tested the only thing I'm missing is namespaces. Concept would be nice eventually but are not that important right now.

There's a few other small things missing in fact, but yeah, namespaces are the big one. Everything else would be fairly trivial I think.

[stephanlachnit]

Is this project open source by the way?

It will be eventually, most code is still private however. If you want to have a peak, feel free: https://github.com/stephanlachnit/constellation-chirp-code

[BrunoMSantos]

Mostly I wanted to know if we would be able to follow your use case more directly. Thanks for sharing, and keep us posted if you decide to use hawkmoth and what works or not for you guys.

[jnikula]

The main issue here is fixed by #247. Please file specific issues on the remaining gaps that you may encounter. Thanks.