#1432 ::REQUIRES documentation enhancement request

[Geoff Stevens]

REXX-ooRexx_4.2.0(MT)64-bit 6.04 29 Dec 2013
Debian Stretch
Reproduce by circular ::REQUIRES, see ticket #969

I ran into issue #969 ::REQUIRES alters behaviour again. Circular references in ::REQUIRES are prohibited, but the failure occurs without an obvious indication of what's gone wrong.

The intervening five years have been long enough for me to forget that, leading to confusion on my part when splitting up some classes into separate files. While it's easy to see in a test program, it took me some time realise the crime I'd committed in a refactoring involving several files and more classes.

May I suggest that the ::REQUIRES directive doc in 5.0.0 rexxref be enhanced to explicitly state that circular usage of ::REQUIRES is invalid? At least I wouldn't have to search the bug tracker the next time I commit this programming error.

[LesK]

Wouldn't it be better to fix ::REQUIRES to ignore the circular reference and issue an Information msg?

[Geoff Stevens]

Yes, I agree that's better, but seems precluded by the response to #969: "Don't do that".

At least a doc update would describe the situation and provide some guidance: "Don't do that". Examples based on the #969 stuff could illustrate the problem.

Really, I'd want to either ignore the circular reference or issue an information msg. By ignore the circular reference, I mean make a class in a ::REQUIRE-ed file act the same as one included in the same source file.

Still, either of those options involve a (for me) unquantifiable programming effort, for what is something of a corner case, reported once in the last five years, and which might be a feature of the packaging system anyway.

A doc update could be incorporated in the 5.0.0 materials with a relatively small effort, I would hope.

Unless someone can point me at existing doc that describes it?