This is a fairly general question. I'm not asking about one specific thing which is confusing me. I'm instead going through my logic about APIs and asking people to tell me everything which is wrong. I really want people to tell me everything they can think of which is wrong. If there are no obvious errors, tell me minor inaccuracies. If you explain something which I don't understand I will try to ask questions to make sure I do. If I'm asking anything which you think I could find out simply by reading up on it, I would be grateful if you could at least point me in the right direction.
I'm asking this question due to a specific project I am working on. This is a Physics Forum thread where I discuss the project (I've changed it a bit since then but only in fairly minor ways -- for example, I am currently not thinking about working on OpenFOAM any time soon). The project is an API for analyzing data from wave lab experiments. While there are many more functions I could consider adding, I think I have enough specific functions to create a somewhat useful API. However, I am still not completely clear on how to do it.
I understand that my functions could either just remain as standalone functions or be incorporated classes as methods. I understand that the advantage of using them as methods is that they can be accessed from multiple places by simply getting a handle to the method. Therefore, I imagine that methods would be pieces of functions which I've used in multiple places. An obvious example would be automaticallys saving graphs, which is used in almost all of my functions. Essentially, I am thinking of methods as tools. On the other hand, if there is a specific thing to be done, it should be a function. An example would be something I was working on today, which uses subplots to plot time series, fourier transforms, and PSD of user specified data. Essentially anything which gives a sort of final output for the user (like a graph) should just be a standalone function.
Using standalone functions does confuse me a bit though. I would imagine I would have many standalone functions because there are many specific things I would want to plot. This would make it hard for me to access them. I could imagine putting them in folders, but then I would imagine this is essentially doing what an API is supposed to do.
I imagine that in MATLAB, all my properties should be constant and all my methods static for what I am working on. Non constant properties wouldn't make much sense becasue the point of the property is to ensure consistency (I want g to be 9.8 always, for example). Methods which aren't static aren't useful because they can't be instantiated according to this.
There are many other questions I have (documentation, how best to use subclasses, how do you use handles to properties), but I think those are the most important issues for me.
If after a day or so there are no responses, I will assume my strategy is fundamentally correct (I will assume for example that putting functions in folders would just be a personal preference and not an indication of something being wrong with my approach). I will then post multiple questions about more specific things. If I understand answers to those, I will begin making an API with a fair amount of confidence that my approach is correct.