Documentation

I’ve downloaded & built several bits. Excellent work.

What I have noticed is a lack of documentation, such as to what some of the smaller tools do. I have only just been looking at better docs for my own libraries in either StrongHelp or HTML.

Do you plan on using a documentation tool (doxygen or such) that could be used by everyone and integrated into the system? I’ve not used anything so I don’t know any implications.

I like StrongHelp manuals whilst I’m programming so ideally I’m thinking along the lines of automatic stripping/conversion from the source code into the docs, but with selectable output into different formats as people require ie PDF, HTML, Text.

I think something like this could give RISCOS a more unified help system and allow programmers to produce better documentation at the same time.

Mitch

Doxygen would only be useful if a unified effort was made across the sources to use Doxygen-style comments. It’s something which he have used and do use but that still means it’s only currently found in probably less than 1% of the sources.

As for documenting the tools, we’re starting from scratch here because most of this stuff isn’t documented in the first place. Much of the knowledge about the RISC OS sources has either been passed down by word of mouth or learned the hard way.

There are no decent documents about doing builds or the like (other than hopefully what I’ve been writing) and each component is like a lucky dip from a documentation point of view – you’ll either have some or you won’t, it’ll either be useful or useless.

So we have to balance our time writing documentation against the time we spend actually getting sources out there. So I suggest that if you have specific questions, by all means post them here. If not, have a stab at working stuff out for yourself and then write up what you find somewhere in our wiki.

:)

I Think My post was unclear, sorry about that and I do realise how busy you must be. I wasn’t asking about particularly about documentation for existing stuff but whether you had anything in place for documenting from now.

I still feel that there should be some sort of overall plan with regard to documenting changes in the system. Everyone could then attempt to follow the same guidelines.

Is Doxygen suitable… If not what might be used? I had thought of using StrongEd Modes for syntax colouring but that could turn out to be a bigger project than I planned.

Anybody got other ideas or maybe a collaborative project ?

I still feel that there should be some sort of overall plan with regard to documenting changes in the system.

I’m not sure what you mean by “changes in the system”, but I assume you mean API changes to module or library components, along with new features or changed features in applications. The Wiki is designed for exactly this kind of material. Help on using and editing the Wiki pages is available here.

At ROOL we’d like to see the PRMs appear there, in full, so that the community at large can tackle updating them to include more recent changes and any changes made from this point on. Whether or not it’s practical to do that without unreasonable amounts of effort and whether or not the Wiki engine is even strong enough to support enough of the PRM typography for it to remain meaningful is another matter. I think we’d also need to port the Instiki PDF export feature back into I2 so that we could generate self-contained documentation too ^[1].

The PRMs made it to HTML format and StrongHelp format too, so I don’t think it’s an impossible task and it’s one I have my eye on for the mid-term future. In the mean time, you can use the Wiki to keep track of recent changes using stand-alone pages – in addition to the change logs etc. that get generated by the CVS check-in process when (well, if) changes are fed back to the ROOL repository.

^[1] Having just seen that Instiki has changed to a new maintainer and underwent its first maintenance release in ages relatively recently, I might consider migrating back to it. That’s a lot of work though and I2 seems pretty robust, so the jury’s out.