Understanding Public and Private APIs in Libraries

[szk2s]

Thank you for your generosity in sharing this fantastic library.
I am considering using this library in my application.

Generally, I believe that libraries have both public and private APIs. Public APIs are typically carefully managed, and any changes are announced as breaking changes.

Is there an easy way to determine whether a certain class/method included in Tracktion Engine is public or private? Specifically, when incorporating Tracktion Engine into an application, is there clear documentation available for application developers to know which classes/methods to use?

[szk2s]

For example, when wanting to use AudioFormatManager, how should an application developer determine whether they should initialize it using its constructor or use Engine's getAudioFormatManager? If using the constructor is discouraged, I believe we can classify this constructor as a private API.

[drowaudio]

The answer is "it depends". The library is constructed in such a way that you can either use it as a full framework stemming from the creation of an Engine object or several bits on their own.

Generally though I'd say you probably want to create an Engine and use the functions to retrieve objects from there so they use the same Engine settings (temp folders etc).

If there are truly private classes in the engine they tend to be inaccessible or clearly marked as such. You generally want to just include tracktion_engine.h as that will provide everything from the library in the correct order.

[szk2s]

Thank you for the clear response.

As you suggested, I will include only tracktion_engine.h, but it still contains a plethora of classes, making it quite challenging to determine how to achieve the functionality I'm seeking. It seems that I will need to invest some time in deciphering the source code before I can effectively use the library.

I have a few feature requests in mind. It would be helpful if there were a way to list classes and methods that can be accessed from outside the engine, typically from the GUI. I believe it can be archieved without narrowing down the available APIs. This could be achieved through the implementation of a facade, header splitting, or the definition of functions similar to those found in examples/common/Utilities.h. Such a resource would significantly ease the process of locating the desired classes and provide reassurance regarding the potential extent of breaking changes. I would greatly appreciate it if you could consider these suggestions.

[drowaudio]

Thanks for the suggestion. The problem with this approach is that we can only cover so much of the API and inevitable users will want more and more underlying functionality exposed. We take this approach to some extent in tracktion_EditUtilities.h to some extent to provide easy access to tracks/clips etc. Once you have those you can interact with any of the public APIs of them.

We try very hard not to break compatibility of the public sections of classes and where internal classes not intended for public use are used internally, we try to either make them inaccessible (by implementing them in .cpp files) or namespacing them as such.

[szk2s]

I got it. I'll take a look at tarcktion_EditUtilities.h. Thanks for the explanation.