Yes, I had a pragma solution using <helpTopic: 'Title goes here'> in one of the first versions - but it gets complicated if you want to define structured help contents with nested books and with pages in a specific order. The implementation is easy ... I mean with pragmas it would be complicated for the "help writer" to define these nested book structures and to remember the correct pragmas.
And you have to solve the following scenario: you may have a class A defining a help book using pragmas and a class B defining another help book which should be displayed under the book defined by A. Since you do not rely on a "help class hierarchy" and are decoupled using pragmas both classes can live under Object. Good. Everything works fine when A and B are in the image. But you can get a problem when class A is not loaded - since the parent book of B is not there.
I would not see a problem in having the help hierarchy clearly defined as a subclass hierarchy of a predefined "CustomHelp" class.
The point is to avoid duplicating code between a class and its help or between a testcase and the help.
Providing CustomHelp subclasses is easy to understand for the "content writer" and system help is not spread around in the image.
Yes but it can also be out of sync. I like literate programming just because the comments are in the code.
You can see the structure in the class hierarchy browser and in the help browser. Thats wonderfull. For all these reasons I would prefer a CustomHelp for the standard help. (Independent from that the help browser itself is still capable to use anything with an #asHelpTopic interface).
Providing the CustomHelp class is the same as with TestCase - you know that when you subclass you will later find it in the UI tool (TestRunner/help browser) and you can peek in other TestCase subclasses to see what is possible.
And yes, that means that minimal help support (in minimum 2 classes HelpTopic and CustomHelp) is already in the image similar to SUnit.
Dont know if the name CustomHelp is good (maybe HelpBook/SystemHelpBook?).
I'm not worried by having two classes extra in the system or core since help will not been referenced from everywhere. This kind of packages are easy to unload. I was more concerned about the idea that we can use the system to annotate what should be promoted as help. Writing separate and maintaining doc is costly and I was thinking that I wanted to reuse as much as possible as the existing information (class comments, unit tests...). Stef