Some fixes to function documentation

[Gary Johnson]

I discovered that some of the functions present in ":help functions"
were missing from ":help function-list". The attached patch:

- Adds missing functions to ":help function-list".
- Puts the ":help functions" list in alphabetical order.
- Fixes some misspellings in doc/eval.txt.
- Cleans up some inconsistencies in function-list.

I didn't know exactly where to insert some of the functions into the
function-list, so I took some reasonable guesses.

The patch is based on Vim 8.2.834.

Regards,
Gary

[Bram Moolenaar]

Thanks. It's easy to forge to add a function in all three places.
Perhaps we should have a test for that.

--
hundred-and-one symptoms of being an internet addict:
198. You read all the quotes at Netaholics Anonymous and keep thinking
"What's wrong with that?"

/// Bram Moolenaar -- Br...@Moolenaar.net -- http://www.Moolenaar.net \\\
/// sponsor Vim, vote for features -- http://www.Vim.org/sponsor/ \\\
\\\ an exciting new programming language -- http://www.Zimbu.org ///
\\\ help me help AIDS victims -- http://ICCF-Holland.org ///

[Gary Johnson]

On 2020-05-28, Bram Moolenaar wrote:
> Gary Johnson wrote:
>
> > I discovered that some of the functions present in ":help functions"
> > were missing from ":help function-list". The attached patch:
> >
> > - Adds missing functions to ":help function-list".
> > - Puts the ":help functions" list in alphabetical order.
> > - Fixes some misspellings in doc/eval.txt.
> > - Cleans up some inconsistencies in function-list.
> >
> > I didn't know exactly where to insert some of the functions into the
> > function-list, so I took some reasonable guesses.
> >
> > The patch is based on Vim 8.2.834.
>
> Thanks. It's easy to forge to add a function in all three places.
> Perhaps we should have a test for that.

I've created a test, attached. It checks that all three lists
contain the same set of functions and that the lists in
src/evalfunc.c and doc/eval.txt are sorted.

This is my first attempt at a test in the new format, so I thought
I'd post it here before submitting a patch to see if anyone spotted
anything I should change.

Also, the test will fail until the original patch of this thread is
applied and another patch to doc/eval.txt is applied as well. Or,
if this test looks OK, I could just submit a new patch with
everything included.

Regards,
Gary

[Gary Johnson]

Darn! Test file actually attached this time.

Regards,
Gary

[Bram Moolenaar]

Thanks!

The test currently fails, as predicted. The error message doesn't give
much of a hint about what needs to be fixed:

Found errors in Test_function_lists():
function RunTheTest[39]..Test_function_lists line 59: difference at byte 2829
function RunTheTest[39]..Test_function_lists line 77: difference at byte 2890

Would be nice to point to what's wrong. Ah, I see that an
Xfunctions.diff file is generated. Hmm, but "diff" might not be
available.

The sorting should be done without ignoring case? At least for a binary
search it should.

I did find that reduce() and searchcount() were not in the function
list, so that works.

--
Emacs is a nice OS - but it lacks a good text editor.
That's why I am using Vim. --Anonymous

[Gary Johnson]

Yeah, but I don't know what to do about that. I suppose I could
save the lists to Lists instead of files and do a rudimentary diff
of two Lists. (Having Unix tools makes life so much easier.)

> The sorting should be done without ignoring case? At least for a binary
> search it should.

The type of sorting seems to differ between lists. The
global_functions in evalfunc.c seems to be sorted in ASCII or "C"
order, which makes sense for source code, while the ":help
functions" in eval.txt seems to be sorted in dictionary order, i.e.,
ignoring case, which is reasonable for documentation. I guess the
latter depends on the expectations of the reader. I tried to follow
what was already there, although that was inconsistent. I don't
personally have a preference.

Regards,
Gary

[Bram Moolenaar]

We probably should make assert_equalfile() better. Show the context of
where the difference was found. However, in this case the question is
also where the list comes from, that could be added as a third argument.

> > The sorting should be done without ignoring case? At least for a binary
> > search it should.
>
> The type of sorting seems to differ between lists. The
> global_functions in evalfunc.c seems to be sorted in ASCII or "C"
> order, which makes sense for source code, while the ":help
> functions" in eval.txt seems to be sorted in dictionary order, i.e.,
> ignoring case, which is reasonable for documentation. I guess the
> latter depends on the expectations of the reader. I tried to follow
> what was already there, although that was inconsistent. I don't
> personally have a preference.

In case of doubt I would prefer to do what ":sort" without arguments
ends up with. It's just easier to maintain that way.

--
hundred-and-one symptoms of being an internet addict:

252. You vote for foreign officials.

[Gary Johnson]

You have a better idea of the style you'd like than I do, but I can
take a stab at that if you'd like.

By a third argument for where the list comes from, do you mean an
optional {msg} argument as used by other assert_*() functions?

> > > The sorting should be done without ignoring case? At least for a binary
> > > search it should.
> >
> > The type of sorting seems to differ between lists. The
> > global_functions in evalfunc.c seems to be sorted in ASCII or "C"
> > order, which makes sense for source code, while the ":help
> > functions" in eval.txt seems to be sorted in dictionary order, i.e.,
> > ignoring case, which is reasonable for documentation. I guess the
> > latter depends on the expectations of the reader. I tried to follow
> > what was already there, although that was inconsistent. I don't
> > personally have a preference.
>
> In case of doubt I would prefer to do what ":sort" without arguments
> ends up with. It's just easier to maintain that way.

I'll fix that in the source and in the test.

Regards,
Gary

[Bram Moolenaar]

Gary Johnson wrote:

> > > > Would be nice to point to what's wrong. Ah, I see that an
> > > > Xfunctions.diff file is generated. Hmm, but "diff" might not be
> > > > available.
> > >
> > > Yeah, but I don't know what to do about that. I suppose I could
> > > save the lists to Lists instead of files and do a rudimentary diff
> > > of two Lists. (Having Unix tools makes life so much easier.)
> >
> > We probably should make assert_equalfile() better. Show the context of
> > where the difference was found. However, in this case the question is
> > also where the list comes from, that could be added as a third argument.
>
> You have a better idea of the style you'd like than I do, but I can
> take a stab at that if you'd like.
>
> By a third argument for where the list comes from, do you mean an
> optional {msg} argument as used by other assert_*() functions?

Yes, mentioning what is being compared already helps a bit.

> > > > The sorting should be done without ignoring case? At least for a binary
> > > > search it should.
> > >
> > > The type of sorting seems to differ between lists. The
> > > global_functions in evalfunc.c seems to be sorted in ASCII or "C"
> > > order, which makes sense for source code, while the ":help
> > > functions" in eval.txt seems to be sorted in dictionary order, i.e.,
> > > ignoring case, which is reasonable for documentation. I guess the
> > > latter depends on the expectations of the reader. I tried to follow
> > > what was already there, although that was inconsistent. I don't
> > > personally have a preference.
> >
> > In case of doubt I would prefer to do what ":sort" without arguments
> > ends up with. It's just easier to maintain that way.
>
> I'll fix that in the source and in the test.

I removed the "i" argument from the sort command and it only found two
places that needed adjustment.

--
hundred-and-one symptoms of being an internet addict:

253. You wait for a slow loading web page before going to the toilet.

[Gary Johnson]

A complete patch is attached. This patch includes:

- a sorted list of functions for ":help functions";
- addition of functions missing from ":help function-list";
- a new test for checking that lists remain complete and sorted;
- fixes to a few misspellings.

The new test uses the new msg argument to assert_equalfile() to make
the failure messages a little more clear. The function lists have
been updated since my earlier patch to include functions added since
then.

An issue with the new test is that if it fails, an external diff
program is required to produce meaningful output files for
debugging. I looked briefly at writing an internal diff function,
but decided that it was more trouble than it was worth and one more
thing to maintain. Also, now that the major problems with the lists
have been fixed, the test should fail only for a developer who has
added a new function and that person should know where the problem
lies.

The patch was based on Vim 8.2.895.

Regards,
Gary

[Bram Moolenaar]

Thanks.

Hmm, not sure why asin() was dropped from the list in eval.txt.
Looks like the diff isn't against head. I'll have to make a patch
anyway, to avoid that the patched version (not the github version) fails
when adding the test.


--
GALAHAD: Camelot ...
LAUNCELOT: Camelot ...
GAWAIN: It's only a model.
"Monty Python and the Holy Grail" PYTHON (MONTY) PICTURES LTD