The untapped potential of Juce

My vote for best documentation in JUCE goes to juce::String::formatted:

Really fills me with confidence when an API’s docs start with “I don’t like this method. I don’t use it”

10 Likes

Similar to the OP, I’m coming from QT and the JUCE documentation (or lack of) is very frustrating. I’ve tried reading the classes but the multiple layers of inheritance hides alot of the functionality. Some basic class descriptions - as others have said - would be helpful.

Another is just a basic diagram of how audio is passed to-from the audio device. It’s taken me alot of debugging with the examples to get just a hint of what is going on.

And w.r.t. audio buffer details, I’ve watched alot of tech talks from Fabian and others about the importance of avoiding mutexes and about using lock-free inter-thread buffer handling, and yet the first thing I come across in the JUCE audio device callback is the ScopedLock; which appears to involve mutexes?! Again, some basic block diagrams would help.

Thx,
Michael

1 Like

A problem I see with the online documentation is that all classes are grouped only according to the module they belong to. But in the source code the classes are actually grouped, within each module, in meaningful folders. For example, within juce_core one finds: containers, files, javascript, logging, maths, etc. This lets you much better browse the code and see where everything belongs. This is another reason, apart from being able to quickly look “under the hood”, why I much prefer reading the documentation from the source code and not online.

EDIT: disregard this. The main window one goes to after clicking on “Documentation” takes one to the list of classes according to “tags” but clicking on “JUCE Modules” reveals the subfolders. I’ll get my glasses fixed!

The onlines docs are separated by folder: JUCE: juce_core

This is really useful because it shows all the free functions JUCE has that aren’t part of any class. For example I’d never known about juce::rawToUniquePtr() before, which would have come in useful many times in the past!

Yes, I was correcting my previous post just now. It’s indeed right there at the top, JUCE Modules!

There seems to be a general trend in C++, not just juce, to have more free functions and not shove everything in a class. I haven’t see any projects that have found a good way to document these free functions. Classes were nice because they are somewhat self documenting.

That said, I don’t really see the point of juce::rawToUniquePtr, looking at how they use it in the juce codebase:

auto midiOutput = rawToUniquePtr (new MidiOutput (endpointInfo.name, endpointInfo.identifier));

auto reader = rawToUniquePtr (WavAudioFormat().createReaderFor (new MemoryInputStream (block, false), true));

return rawToUniquePtr (new ARAHostDocumentController (std::move (impl)));

What does this gain over just using std::make_unique or the unique_ptr constructor?

There are a couple of use-cases for rawToUniquePtr:

  • The main benefit is that it can deduce the type of its argument, which makes it easier to use and more concise than writing out the template argument of the unique_ptr constructor. This is what’s happening in the second example.
  • On some compilers, make_unique cannot be used to call a private constructor of a type. In these situations, we instead call new directly, and then wrap the result into a unique_ptr using rawToUniquePtr. This means that there’s no need to repeat the name of the type being constructed. This is the reasoning behind the first and third examples.
4 Likes

It’s a complicated topic, but in some cases using locks is the most straightforward method to deal with thread safety issues. Juce uses quite a lot of locks in its internal code, but that doesn’t mean you should use even more locks on top of that.