Hi,
I want to use Juce for a rather complex Audio tool/plugin. So I did read the Juce Tutorials and watched Juce tutorial videos. I think I have a good enough understanding to start coding.
But when I look at the documentation I realize that I only know about 1 % of the available classes. I’m sure I can use much more of them if I know more about them.
I worked with Qt for years. When I needed some functionality I looked at the available classes. The documentation perfectly tells me for each class what it does and how to use it.
But for Juce the description of the classes in most cases is useless! In a lot of cases only one line with very limited information. From that description you will not be able to know what the class does and how to use it. For some classes it may be clear what they do just looking at the name and the functions. But for a lot of classes this is not the case. At least not for me. That is a shame because because of this I will (can) not use more then 50% (or so) of the classes.
I know there is the DemoRunner. But only a fraction of the classes are used in these demos.
I would like to be able to read a few lines of description for each class so that I understand the building blocks I have available to make my tool/plugin. I does not need to be a full page. Just a few meaningful lines. It will cost a Juce Engineer only a week or so to create a meaningful description for each class (explaining what it is for and how to use it). Juce will probably used more and so this will pay of easily.
I feel like I can not use the full potential of Juce. And I feel bad about that, because I want to!
More robust documentation is always a good thing! But, do you have some examples of some of the classes you don’t understand? I ask because the first piece of documentation is the naming, but obviously that doesn’t help if you don’t have any contextual experience with the domain the API covers. Second, if you are hoping this new detail in the documentation to learn new things, how do you know which ones to read? Lastly, I think it is poor form to express an expectation of the time required to do this. As an engineer of many years, my work speed drags to the minimum when needing to write documentation. There are professional documentation people for a reason. In the short term, feel free to use the forum to ask for clarification.
Usually when you commission documentation you get things like:
double getSampleRate() : returns the current sample rate.
But I agree, the introductions for the classes could be a bit more verbose, giving more cross references.
Many people miss the existence of some classes and roll their own, or use classes for purposes they were not intended to like my pet peeve AudioTransportSource…
But it is a time sink, and I am not sure how valuable it is, as you will quickly become accustomed to it.
I love JUCE. I also love Tracktion Engine. I think they’re amazing tools to get the job done.
It takes a while to get used to inferring implementation details from the code and examples. Honestly, I get that this can be rather frustrating.
I wonder if this is due to JUCE’s origins. I’m not well versed in its history. Tracktion Engine was most certainly closed source for a long time, and so there wasn’t enough of an incentive to write detailed documentation.
My firm chose to write a library around JUCE and we’ve added extensive documentation to that library. To us, that was the easiest solution.
double getSampleRate(); // Returns the current sample rate as a double
// TODO add setter
Which of course then doesn’t get updated when the code changes, so you get wonderful documentation like this:
float getSampleRate(); // Returns the current sample rate as a double
void setSampleRate(float);
// TODO add setter
IMO JUCE’s documentation is just right - enough to give you some details about the implementation of things, but not so much that you spend more time reading than actually writing code. Most things are very intuative and so you don’t really need any documentation, e.g. juce::Point what more documentation do you need than the name itself and the list of public methods?
There are definitely some areas that could be improved - for example the documentation for juce::RSAKey provides code examples for Java, and PHP, but doesn’t actually provide a code example of how you use juce::RSAKey itself!
juce::Point is actually a great example of where some small refactors to the code itself are far better than documentation. E.g. it currently has this line
The ValueType template should be a primitive type such as int, float, double, rather than a class.
If you instead changed the name ValueType to ArithmeticType and added static_assert(std::is_arithmetic<ArithmeticType>()) you don’t need that line at all as the interface and the compiler will tell you the same thing.
I would read the description of the classes I do not know yet so now and then. This to get a better understanding of how things work together and to be able to use more and more classes from the framework in my projects.
For me a description when to use it and how to use it would be sufficient. A piece of example code would be better of course. But only needed as a main example. Not per function. But when a function is not trival, there should be a good description for it.
I would even spend some money for such documentation (book?).
Hmm if it’s example you want I wonder if it would be possible for us to add links to places where the classes are used? A lot of stuff is used in the DemoRunner for example.
It would be really handy to have a link to the correspnding file on GitHub in the docs for when you want to look a bit deeper into the implementation rather than just the interface.
That is a very valid answer, but doesn’t help the OP.
I would definitely look at the examples, the tutorials and the DemoRunner. They are gold.
But for a high level description, like what are the driving forces of the pipeline, how does the look and feel workflow work (like lookup to parents), how is the colour determined inside the components. Those are also valid questions, and it takes a while until you have all digested.
I guess somebody could write a book about it, and e.g. @kerfuffle did with
That book is not advanced enough. Only basic stuff. Like all the video tutorials about Juce. They explain how to install Juce, how to start a new project with Projucer and how to write a very simple plugin.
As a professional developer I can tell you that I have a few strategies for addressing this situation, which work for me:
Read the Classes.
Yes: Read The Code.
The Code IS Documentation.
The JUCE (and Tracktion) framework codebase is pretty easy to navigate. It would take a week for a newbie to get through reading the classes, class by class, and getting a feel for what they do.
Take notes, make your own bread-crumb trail through things, but whatever you do: make the time, and take the time, to read the code.
Bonus points if you make a fork and add your own comments as you do this, over a week or two, so that it can be easily shared with others.
awesome-juce. This is such an excellent resource, I have a script for setting it up on all of my JUCE development workstations, and I use sudara’s cut trick[1] (s/echo/git clone/) to clone every single repo in the list.
Yes, really. I clone every single repo in the awesome-juce list, and then I READ THAT CODE TOO.
Then I set up my editor to parse this massive archive of existing Open-Source projects, and any time I encounter an issue with a JUCE/Tracktion class, I check the repos. More often than not, I find good practices - or, at the very least, examples from others who have already worked things out a bit.
Join the Discord, and find other JUCE coders to discuss things in realtime.
Many times, you will find an enthusiastic colleague who might spend a few minutes with you, if you lure their eyeballs into the chat with a well-worded, balanced and interesting question about any particular subject. Please note, this will be far, far more effective as a strategy if you do #1/#2 above, first, stringently.
If you’re still stuck, formulate a decent post to the forum, sit back and wait.
The JUCE Devs have detectors for when all of the above have been done, and are more than likely going to respond with enthusiasm to help you under those conditions.
Another vote here for reading the code. That’s the big advantage of actually having the code, so you can read it. Fortunately, the JUCE code is quite readable!
I think this is a nice idea. The other thing I feel is missing from the docs for a some classes is a sentence on what you would use the class for.
Good example:
" Subclasses of AudioFormat are used to read and write different audio file formats"
Ah great, I need to write an audio file!
Not so good example:
“This object allows an asynchronous callback function to be triggered, for tasks such as coalescing multiple updates into a single callback later on.”
Hmm, can I use this to pass information to my background thread? Ooh, or maybe it’s an async thing and I should use it when I’m making a blocking network request?
This could be improved with some sort of “AsyncUpdater has many uses but is often used to link a UI element to a plugin parameter than can be modified on another thread.”
That is exactly what I mend. Just a few lines to explain where it is for and how to use it. So that you can use it when needed and so that you do not use it in wrong places or in a wrong way.
Their names are quite self-explanatory so you can quickly learn what is available for you in each module. With that said, you will have to click on some classes and read their code to understand well what they do.
Would be nice if it would tell which one is what, since they are always confusing which one to use.
If you want to be over-achieving, a screenshot of each would x-mas come early
In the short term, feel free to use the forum to ask for clarification.
