As someone who has written dozens of toolboxes, with literally hundreds of functions, and someone who tends to be a manical perfectionist about my own documentation and code...
I'd suggest you are being rather hard. Useless? Really? Seriously? That is just hyperbole.
Simplistic examples? Um, if you don't provide at least some simple examples, then most users will get blown away, having no clue at what the code even does.
Make your examples too complex? Then most users will not bother to read them. Instead, they will just ask innumerable questions on Answers, expecting us to rewrite the MATLAB documentation completely for their personal pleasure.
Is documentation perfect? Of course not. It cannot possibly be saisfactory for every person. As a documentor, you make up examples, you try to cover all use cases you can think of. At some point, you decide that you have done enough, that someone who really wants to use the tool in more depth will be able to make logical extensions of what you have told them already. For example, suppose I was an author of the curve fitting toolbox. (I'm not, but I could have written it, and I wrote my own version of it before the CFT ever existed.)
In the help for fit, I see examples of simple polynomial models. Thus we see 'poly1', 'poly11', 'poly2' as examplary of polynomial models. Surely the user can extrapolate to understand what 'poly5' might indicate. So as a documentor, you go as far as seems reasonable, and then you stop. Otherwise, people will claim you are too wordy. (In fact, I found one user of my toolboxes who claimed that my documentation tends to be TOO extensive. Surely other uses have thought I stopped too soon. How could I possibly win there?)
Now, look at the output of fit.
[mdl,G,O] = fit(rand(100,1),randn(100,1),'poly1')
Linear model Poly1:
mdl(x) = p1*x + p2
Coefficients (with 95
p1 = -0.5169 (-1.221, 0.1867)
p2 = 0.1436 (-0.2596, 0.5468)
struct with fields:
struct with fields:
residuals: [100×1 double]
Jacobian: [100×2 double]
algorithm: 'QR factorization and solve'
So, what might I need to explain there? Most of the return arguments seem self explanatory. G is described as "goodness of fit measures". But at some point, I'd need to stop writing. Do I need to have an in-depth description of what rmse means? Of what an r-squared measure means, or why one might sometimes need an adjusted r-squared measure?
What I see in the help are things like this:
-- SSE sum of squares due to error
-- R2 coefficient of determination or R^2
-- adjustedR2 degree of freedom adjusted R^2
It seems eminently reasonable to me. But the fact is, if someone is wanting to use these tools, without even a clue about empirical mathematical modeling, about regression analysis, they will be completely confused. At the same time, to provide sufficient docs for that (clueless) person to use such a tool, this would require posting a complete statistics textbook in the help.
As far as what you can do with a fitted model, to some extent, you need to understand MATLAB. mdl is seen to be an object, so you need to look at the methods that apply.
Methods for class cfit:
argnames coeffnames dependnames fitoptions integrate numcoeffs probnames type
category coeffvalues differentiate formula islinear plot probvalues
cfit confint feval indepnames numargs predint setoptions
Again, most of them seem logically named. But it is required that the user understand MATLAB to get the fullest utility out of the results. To get there, documentation already exists. If you want to differentiate a model, then differentiate seems right. If I have no clue what differentiate means, then I should be taking a basic calc course, and probably not even trying to use MATLAB to do that yet.
So as a writer, you go so far, then you stop. Yes, there is probably some overview of what goes into the docs, but as a proofreader of documentaiton at TMW, they will see what is written, and possibly decide it is sufficient. Will it be sufficient for everyone? OF COURSE NOT! But if they tripled the size of the help, then too many people will feel overwhelmed, not getting through it at all to the important spots. You try to find a happy medium.
As a user, nothing stops you from suggesting documentation patches, additions where you feel the docs were incomplete. I have done so myself in some cases.