(Non) empty description in .swi files

[John Tytgat]

In message <4961D910.7030706 at vanderhoff.org>
          Tony van der Hoff <tony at vanderhoff.org> wrote:

> Erik Groenhuis wrote:
> > As John Tytgat wrote on 31 Dec 2008:
> > 
> Hm, meant to repliy to the earlier posting:
> 
> [snip]
> 
> >> Any reason for this inconsistency ? Is there an usecase to limit the
> >> use of SWIs without description (and without a star) ?
> > 
> I don't think so. I rather suspect it's a bug, which has not been picked 
> up throughout OSLib's lifecycle. I would agree it needs fixing.
> 
> However, looking at the grammar, I note:
> 
> description:
>     DESCRIPTION
>        {  tracef ("DESCRIPTION \"%s\"\n" _ $1);
>           $$ = Empty;
>           $$.description = EMPTY ($1)? NULL: qstrdup ($1);
>           $$.starred_swi = TRUE;
>        } |
>     STAR
>        {  $$ = Empty;
>           $$.description = NULL;
>           $$.starred_swi = TRUE;
>        };
> This looks like it's intended that the STAR case is treated the same as 
> the EMPTY case, and that therefore something is broken elsewhere.

It took a while before I could investigate this in more detail and it
turns out that above DESCRIPTION implementation is highly misleading
as $1 never can be NULL (nor empty string).  An empty description is
actually being dealt with DESCRIPTION_option in the defmod.y file and
this never drops to DESCRIPTION case.

There is a difference between an empty description case and having
a star as this is currently usefully being used to make the difference
between standalone SWI entries without description (so a description
gets automatically made up) and having reason code based SWIs (the
difference is e.g. the #define output in the C header files).

I've updated DefMod's Manual documentation, added test cases to
illustrate the differences, added a couple of warnings to notify cases
of no description or double descriptions (which wasn't clear if this
would result in a standalone SWI or reason code SWI).  And fixed
the .swi files after seeing those warnings.

John.
-- 
John Tytgat, in his comfy chair at home                                 BASS
John.Tytgat at aaug.net                             ARM powered, RISC OS driven