(Non) empty description in .swi files

[Erik Groenhuis]

As John Tytgat wrote on 31 Dec 2008:

> One OSLib user notified me that the PCI.Hdr assembler header did not
> contain all the SWI definitions as mentioned in the pci.swi file while it
> was the case for the generated PCI.h C header.
> 
> This is indeed the case and seems to be dependant on the fact whether
> that SWI has a description in the .swi file or not.

[snip: generated C header]

> So there is no preprocessor #define for the SWI without description but
> there is a function prototype generated (and not shown here, but also
> the ARM code wrapping those SWIs are generated).
> 
> The generated assembler on the other hand:

[snip: assembler header]

> I.e. in line with the generated #defines (without a definition for the
> SWI without description) and no way you can use that SWI via assmebler
> (but you could via the C header).
> 
> Any reason for this inconsistency ? Is there an usecase to limit the
> use of SWIs without description (and without a star) ?

>From a pure user perspective this looks like a bug. I would expect
#defines and assembler symbols for each SWI described in the .swi file,
independent of any description given.

> My proposal is the make the empty description case the same was the
> 'star' case, so an artificial description gets automatically
> generated.

I expect that SWIs without a description will be left out of the
generated StrongHelp manuals, and SWIs with a star will be included.

This might be a feature that is currently in use, so the distinction
between no description and 'star' should remain. This should be checked.
If this is the case, the problem would have to be solved in another way.

On the other hand, the quoted documentation does not mention the 'no
description' case. This would suggest that it is an unfortunate
by-product of the parser, maybe intended to allow liberal input.

In that case your proposal is a good one. I'd also suggest making the
'no description' case an error, demanding a description or at least a
star. In case there are too many uses of 'no description' in the
existing .swi files, I'd suggest making it a warning. Both error and
warning should preferably be controlable with switches (e.g. "suppress
'no description' warning", or "reduce 'no description' error to a
warning".  

-- 
Erik Groenhuis http://www.xs4all.nl/~erikgrnh
=== http://www.irregularwebcomic.net/ ===