Just wondering if you guys have API docs somewhere I missed or planning to release one at least for the stable version?
Or, for the newbie, how would I go about generating this? I have never used Doxegen fr C++ reference creation.
Click “Learn” on the top of this page 
Although I find it much easier to use my IDE to jump around the relevant classes - all the API docs are generated from comments in the source code so it’s the same info.
Note the Tracktion Engine tag in the question. 
And yeah, it does look like the Tracktion Engine is a bit light on the documentation. It would likely be in the source code itself if it existed.
Sigh… that’s going to catch me out more than once.
4 Likes
Jules even made it blue!
1 Like
Sorry, in my defense, I was actually going to write “Tracktion Engine API” in the title but my programmer head said DRY! 
I do this exactly as well, but it’s nice to have a condensed list of API with signature summary (not necessarily comments).
Back to the OP, maybe eventually but it’s not at the top of the priority list right now.
One reason is that I feel the same as @t0m in that I’m not sure how useful the online docs are? I never use the JUCE ones, it’s much quicker to contextually jump around in an IDE for me.
The second (and more important one) is that the documentation is still lacking in places. There’s a huge amount of code to document here and up until a fortnight ago it was rapidly being changed so writing docs for it was a futile task. Obviously now the API has stabilised a lot more we will be continuously adding comments but this won’t be an overnight thing. (I have to remember what it all does first 
).
Finally, doing this will take web resources and automation etc. to keep it all up to date and that’s just not something we have right now. Once things free up a bit we’ll take a look at how this should work.
Hope that explains the situation.
1 Like
Yup, totally fine with it, just was curious. Thanks!
I do want to add that the source code IS pretty much self documenting if you give it your all and get some muscle memory with it.
Yep, that’s the other reason we haven’t made comments a huge priority, the code is fairly self-documenting. There’s just a lot of it!
1 Like
I think this is fine when you already know your way around a class - when you don’t then having a top level overview that you can hyperlink around is really helpful.
1 Like
+1 for more docs in tracktion_engine, tracktion code is written really well, but often I spend a lot of time to understand what it can gives me, its potential or the logic with which things are implemented. I agree with @leehu 
4 Likes
I’ve been trying to learn the basics of of Tracktion over the past few days, and found this thread while looking for documentation. As a beginner, I too would love to see full documentation for Tracktion just like in JUCE, but I do understand how much work this would be and why it might not be a priority at the moment. I want to suggest, though, that this needn’t be an all-or-nothing situation, and that a little more documentation might go a long way.
For example, having a list of all the classes available is really useful. I eventually found that there is a class list in the Tracktion header file, but it wasn’t obvious and I’ll bet that some users won’t find it. So copying the list somewhere else in the documentation, or directing us to it in the readme file, would be a very useful thing.
Secondly, while documenting every method might not be an option right now, it is very useful to have a brief description of a class at the top its header file. Some Tracktion classes have such a description, but not all. It might not be important for every class to have a description, but it would be very helpful if the more important ones did (ie. Track and Clip).
Others have mentioned that the code is self documenting, and I look forward to getting to the point where I can learn it and put it to use at the same time. After going through the tutorials quite carefully, I feel that I’m not quite at that point, but I’m also not far off. Just a few more bits of documentation here and there would be really helpful.
2 Likes
Having spent a few more hours at it, I’ve realized something important: it’s a lot easier to understand Tracktion Engine code once you understand Waveform! “Automation Track” and “Step Clip” seem pretty abstract until you see them in action–then they become self evident. It seems obvious in retrospect, but I’ll bet I’m not the only one who will make this mistake!
To anyone else who is looking to demystify Tracktion Engine but hasn’t used Waveform, I highly recommend looking up some basic Waveform tutorials, to give you a better sense of what the classes actually look like.
Tracktion developers, it might help new users if you could put a line about this in the readme or the tutorials: “When learning Tracktion Engine, it is important to be familiar with some of the basic functions Waveform, as a lot of the terminology is aligned”.
3 Likes
Couldn’t agree more, the Waveform 9 user guide PDF is a very good resource for that too, since the class names seem to align pretty well with the terminology used in the user guide.
I’ve finally got around to generating doxygen docs for Tracktion Engine: https://tracktion.github.io/tracktion_engine/annotated.html
These are still a work in progress. Still lots of stuff to be documented.
7 Likes