Re: [Gretl-devel] function arg defaults reloaded (and other doc issues)
On Fri, 7 Apr 2017, Sven Schreiber wrote:
several documentation-related issues, perhaps in time for the
release?
Perhaps!
First, relating to the User Guide section 13.4 (function programming
details):
- An old sin of mine: Here in this thread
http://lists.wfu.edu/pipermail/gretl-devel/2016-January/006447.html I sort of
promised to document the fact that you can give a plain (non-pointerized)
null default for a matrix argument to a function, but I never did that. So
the documentation is still not reflecting this. Or more generally: A
paragraph about matrix arguments is missing in that section.
OK, registered.
- It should be explained how to specify default arguments for int and
bool
arguments (especially without the need for pointers).
I think that should be quite clear in chapter 13 of the User's Guide
(subsection "Function parameters: optional refinements"). What's not
clear?
- In section 10.8 there is a paragraph "Arrays as function
arguments" which
IMHO should be moved into section 13.4, with only a reference remaining in
section 10.8. (In that paragraph there is a footnote about arrays of lists
which doesn't even exist in hansl, so I think that footnote just causes
confusion and should be simply deleted.)
- Similarly in section 10.7 there is an analogous paragraph "What are bundles
good for?", and I think that also belongs better in the function programming
section 13.4.
Fair enough, in both cases.
Then I guess section 13.6 about old-style functions can be removed by
now.
Agreed. That's now gone in git.
Next, two issues with respect to the "Hansl primer" chapter
9 (user-written
functions -- caveat: I'm looking at the June 2016 version, maybe not up to
date):
- Both the listings of possible return types and of possible arg types are
missing the array types "matrices", "strings", "bundles".
That's still the case, and it should be updated. There's also a bit
of a problem with having user-functions documented in both the Guide
and the Primer: changes/updates have to be synced to both documents.
- There's a "Beware" pointing hand explaining that
there are no multiple
returned objects in hansl. Here it probably would be good to repeat the hint
that pointerized arguments are another possibility to retrieve more stuff.
OK, registered.
Ok, so much for now. And no, I don't really have time to apply
these changes myself right now, because properly finding and
disentangling these issues was already quite time-consuming.
Thanks for the disentangling!
Allin