Current status

[Krzmbrzl]

Hi there,
What is the current status of this project? From the outside it appears as if development has mostly stalled and the latest release being 0.x seems to indicate that this tool is not yet meant for production use.
Are the observations correct?

[saraedum]

From the outside it appears as if development has mostly stalled

That's correct. I am using a heavily modified version of standardese to create documentation for a couple of projects "in production". Unfortunately, there's still a fair bit of polishing needed to be able to call this 0.6.0.

the latest release being 0.x seems to indicate that this tool is not yet meant for production use.

Yes, I think that's correct.

Help with this project is always very welcome. If somebody wants to try things out, I might be much more motivated to sit down and finish 0.6.0. That said, I don't intend this project to be maintained and developed by myself only ;)

[Krzmbrzl]

Could you perhaps give a short list of like the most important features / issues that currently make this mostly non-production ready? I'd like to get a bit of a feeling of what currently is supported and where the issues are (generally) located...

I'd love to help out, but I am rather short on time as it stands already xD
Perhaps, if standardese is good enough to be used in one of my projects, I might find the time and motivation to fix/implement stuff that currently bothers me :)

[saraedum]

Could you perhaps give a short list of like the most important features / issues that currently make this mostly non-production ready? I'd like to get a bit of a feeling of what currently is supported and where the issues are (generally) located...

Not sure which version you are referring to exactly, but most code bases eventually run into cases where the cppast library gets confused by something. Usually, one can manage to work around by adding a #define that detects that standardese is running. It's not pretty of course and in my experience only some very intense template wizardry needs this. (Where autogenerated documentation would probably have been somewhat useless anyway.)

More problematic for some is the lack of C++20 support here. So we don't render concepts and such at all.

Finally, the documentation often requires a fair amount of tweaking to look pretty and standardese does not provide too many hooks to do so. It really depends what you are trying to achieve and what kind of documentation you are trying to produce. Here's for example the documentation for a project I am maintaining https://flatsurf.github.io/e-antic/libeantic/doc_renf_class_hpp/. It tries to look like the Sphinx documentation of a related family of Python projects but you don't get this out of the box easily.

Do you have any (open source) code that you are trying to document in mind?

I'd love to help out, but I am rather short on time as it stands already xD Perhaps, if standardese is good enough to be used in one of my projects, I might find the time and motivation to fix/implement stuff that currently bothers me :)

I believe that that's the attitude you'd need to work with standardese. You'll likely run into things you're unhappy with and you'd need to send in patches to get these things fixed :)

[Krzmbrzl]

Not sure which version you are referring to exactly

Current master (or 0.5.2 tag), I suppose 👀

Do you have any (open source) code that you are trying to document in mind?

I'm thinking of using it with https://github.com/KoehnLab/lizard. It's C++17 and tries to keep templating to a reasonable minimum, so I guess that makes the issues you raised (probably) irrelevant for my use case 🤔

Maybe I'll just give it a shot and see how it goes with the current code. The only thing that bothers me a bit is that we are required to use backslashes to mark stuff in doc-comments (e.g. \param). I much prefer using @ for this.
I suppose this would be a first change that I'd have to work on - but first I'll have to figure out how complicated that will get ^^

[saraedum]

You should be able to change the comment.command_character from the command line to something else than \.

[saraedum]

I suppose this would be a first change that I'd have to work on

Contributions are very welcome. It's best to create an issue here first because I might already have something in the making for some things. (I'll try to reply quickly.)

[nyabinary]

any updates?

[saraedum]

any updates?

No, not really to be honest. I haven't worked much on standardese in 2023 and there were not really any contributions from the community either.