BatMgr icon location

When the entire code is available and can be read, refusing to document certain calls as they are “something internal” is little more than purile childishness, a mentality from when RISC OS was closed.

Has there actually been a “refusal” to document the SWIs or have they simply not been documented? Bear in mind that the PRMs were written back when the OS was closed. Since opening it up, has someone actually said “no, we won’t document them”?

Bear in mind that the PRMs were written back when the OS was closed. Since opening it up, has someone actually said “no, we won’t document them”?

There’s also the not so minor point that, as yet incomplete, PRM info is there in wiki form so if anyone has figured out any element that isn’t documented it’s a mouse click and typing exercise to change the situation.

There is of course the question about whether anything with no public documentation has any “secret” documentation which could be opened.

When the entire code is available and can be read, refusing to document certain calls as they are “something internal” is little more than purile childishness, a mentality from when RISC OS was closed.

I completely disagree. The PRMs (should) document the OS public API and its behaviour. There are all kinds of internal stuff that might be interesting (and you can read the source code to find out) that should never be relied on when developing software. It is entirely logical to declare certain things as “internal” and yet mention them for completeness (“look, we have not forgotten it, but do not use it!”).

It is a fine line between documenting too much and documenting too little. A lot of things are undocumented in RISC OS world, but the PRMs are not the place to document most of them. Internal stuff changes frequently, so the docs have to change frequently as well. The one thing that is worse than “no documentation” is “wrong and/or outdated documentation”.

So where do we document internal stuff? The PRM public API made sense when RISC OS was a closed OS. But now there’s a bunch of “internal” things, the specifics of which are known only to a select few. How does that go for encouraging future development by others?

Internal stuff can be documented on the wiki (just make sure it’s clearly marked as “for internal use only”, like all the HAL calls), or in CVS (source code comments, text documents, etc.), again trying to make sure that internal things are marked as such.