Dev/modules doxygen?

[bdejong]

Hello Guys/Jules,

What's the best way of generating the doxygen docs for Juce "dev"? The docs on the site aren't the latest and some classes are missing (because they were obviously added after the last release). Is there some kind of nightly build URL I should know about?

cheers,

- bram

[jules]

I don't currently have a neat way of doing this.. My doxygen scripts are all a bit hacky and won't run on other people's machines, which is why I've not released them. What I should really do is to have a dev docs section on the website that I can keep up to date, but I just haven't got around to sorting that out.

[bdejong]

Is there any way community members could help?

- bram

[jules]

Thanks, but probably not, it's just involves me writing some scripts to auto-update my website.

[jules]

FYI, I've put a copy of the latest docs up here:
http://www.rawmaterialsoftware.com/juce/api_latest/classes.html

[bdejong]

Cool! Thx Jules!

I guess that now with the modules it would be cool to be able to see which class is contained in which module in the future - but I don't suppose that's too easy!

- bram

[jules]

I guess that now with the modules it would be cool to be able to see which class is contained in which module in the future - but I don't suppose that's too easy!

Yeah.. I need to do some research in doxygen and see if it has any tricks for doing that kind of thing.

[X-Ryl669]

Yeah.. I need to do some research in doxygen and see if it has any tricks for doing that kind of thing.

You can use the "@addgroup" for this, or, probably better, you should put your modules in different namespaces.
Nothing prevent you from doing "using juce::audioProcessor" in the final meta-module file, yet, Doxygen will put your classes in the right namespace.

[jules]

Hmm. Using @addtogroup works, but I'd take me hours to plod through all the hundreds of classes in the library and add that to their comments..

[X-Ryl669]

That's seems the worst issue to me.
Putting modules in namespace is a better solution IMHO.
If you run your plan till the end, we'll end up in multiple user-written modules with user-specified (loosy) name and they'll probably overlap. So I think it's a sane way to use namespace for what they were designed, starting now.
You don't need to change much of the code to support namespace'd modules, since you only need to modify the "BEGIN_JUCE_NAMESPACE" macro for each module.

[jules]

I'm a bit reluctant to use namespaces because lots of people will have written code that just has "juce::" everywhere, which would need changing. I'm also keen to keep the namespaces short. But I understand your point, and was thinking about it - maybe it's something I'll change in the future.

But as far as doxygen goes, using namespaces actually wouldn't be any easier than adding @addtogroup, because annoyingly, doxygen doesn't actually parse all the code properly, it just reads each .h file separately, so unless every .h file contains a namespace declaration, it won't know about it. And the way all my code is structured, none of my headers contain any namespace info, except for the top-level ones. So for this to be visible to doxygen, I'd need to add a (doxygen-specific) namespace to all those hundreds of files.

[X-Ryl669]

people will have written code that just has "juce::" everywhere, which would need changing

You can inject types using typedef or using and it'll just work (I'm doing this all the time). Anyway, it's a good pratice anyway to use namespace, so the later you wait for using them, the harder it'll be.

I know you don't put any code for "BEGIN_JUCE_NAMESPACE" in all files.
Now, depending on how you intend to document the modules:
1) A whole module is in its own namespace, in that case, you can stick a BEGIN_JUCE_NAMESPACE in the main header file, and only let Doxygen parse this file.
2) You want Doxygen to see each file separately, and in that case, you might have to perform "search & replace" in all files for some regexp "^class(.*)$" and replace by "BEGIN_JUCE_NAMESPACE\nclass \1\n". Using sed in multiline mode can be straightforward for this task.

[jules]

1) A whole module is in its own namespace, in that case, you can stick a BEGIN_JUCE_NAMESPACE in the main header file, and only let Doxygen parse this file.

Yeah, that's what I'd like to do, but like I said, doxygen doesn't work like that. If you tell it to parse juce_core.h, it won't actually open up any of the files that get included, it only looks at the top level header file.

(And yes, I could write a script to do a smart replace, but there are lots of edge cases, it'd still take me ages to check its output)