Macros can make the min-api more difficult to understand
This is more of a personal observation: as I've been playing around with the min-api, which I find quite nice and clean in terms of the overall design, I keep arriving at the conclusion that the use of macros, like MIN_FUNCTION and MIN_ARGUMENT_FUNCTION, which hide important parameter signatures and return values of the lambdas or functions they replace, may make the api more difficult for newcomers to understand, especially if they are coming from using the c-based max-sdk.
This was indeed the case for me: I found the long form conveyed a lot more information than the abbreviated macro usage and end up replacing all instances of MIN_FUNCTION with the more readable:
[this](const c74::min::atoms& args, const int inlet) -> c74::min::atoms
which can be shortened if one has `using namespace c74::min;` to:
[this](const atoms& args, const int inlet) -> atoms
and similarly, all instances of `MIN_ARGUMENT_FUNCTION`with the clearer and only 2 chars longer:
`[this](const atom& arg)`
To be fair, I'm not all suggesting to remove such macros, as I assume once you get used to the api, you can reach out to the abbreviated form more readily, but just in the beginning of the learning curve, they read like an intermediate DSL on top of supposedly hairy c++ details , except that once you want to do anything that's not basic, you have to understand what lies below and notice that the c++ details, at least the ones that are not complex templates, are relatively straightforward.
S
I see your point, actually both of them :)
When I got started writing my first external I used the min-api/min-devkit and I appreciated a lot the simplification by abstracting away things. It didn’t took more than maybe 30 min to have my first external running. I felt sooo competent all of a sudden. :)))))
The learning curve was much steeper when I wanted to do things outside the min box.
I don’t think it was because things were abstracted, but rather because the documentation doesn’t cover these parts.
I do understand that for Cycling 74 this is not within the first priorities when they need to allocate developer time.
Personally I’d wish that there was an open wiki like way to contribute to he documentation and faster more predictable responses on GitHub to contribute. I made one successful merge request to enhance a little the dict min API, but other proposals remain unanswered unfortunately.
I also had the same initial impression, but as Jan said I think the main problem is the lacking documentation. Most modern IDEs (i.e. anything that's not xcode or vim) should allow you to quickly lookup and/or expand macros though:
Also, I'm not sure if this is of any help, but a huge portion of the min-api is actually documented in doxygen style, meaning that it's possible to generate a full HTML documentation from it. I can see why it's not published publicly since there are a lot of classes etc. that aren't covered (I'd say coverage is about 60-70%), but if you're using a docset reader (e.g. Dash) you can access it locally:
There's no information in there that's not already available in the code, but sometimes just having a quick searchable overview gets you a long way!
Either way, putting it here if anyone is interested:
Thanks JBG.
Good point about IDEs and thanks for providing the docset. I'll checkout Dash to see if I can read it.
I mostly use sublime text without intellisense with the relevant headers open in another tab and then just see what breaks in my compilation output while searching the api via ripgrep. I'm less distracted this way, but it can be inefficient if one is learning a new api.
I do use Visual Studio or Zed on occasion, in case I want to use something with more features and to mix things up.
If I recall it right, the min-devkit started as a way to write C++ externals and packages directly from within Max. Maybe to substitute Java one day? Who knows.
That path is not followed up anymore- for good reasons I think.
I recently got the impression that the min-api is gaining new popularity.
Having a more open/agile platform to contribute to documentation and the code could give it a second live I believe.
@JBG I checked out Dash but I noticed it has a yearly subscription which is not so interesting to me.