Documentation

[ReneK]

I was thinking about documentation lately. Thing is, that there is a standard way of how documenation should be done, provided by Omi initially.

I see the following problems:

1) there are many modules in the BBF that have a documentation like this:

"This module has a private interface, it is only used internally."

That's fine for a commercial product, but not appropriate for an OpenSource project, I think.

2) Documentation is always outdated as soon as something new is done.

3) CPC provides tons of susbsystems, but in large parts does not do documentation the BBF way.

Is there a good reason why we should consider to change the principles behind the BBF documentation and switch to the way CPC does it? If so, what's the reason? And if we changed, we would need to incorporate this in the BBF, so that Info->Documentation still works.

If we stay with the current system, I would suggest to incorporate something like JavaDocs in BBF, so that we can automatically create a skeleton document for every exported CONST, VAR, TYPE or PROCEDURE from the source code. This should include information from the comments, but also things like ASSERT rules. Where necessary, the docu file could then be expanded.

This way, we could quickly produce docu stubbs for the currently undocumented modules, and we could provided documentation for new modules more quickly. Also, this would help users produce their own docus.

[Josef Templ]

BB has already an extensive set of conventions regarding the documentation structure;
see 'Documentation Conventions'. It should also fit to CPC subsystems.

Ok, there are gaps that should be closed and inconsistencies that should be
fixed. Helmut adapted all the documents that are affected by the 1.7 changes
in a very decent way, for example.
The docs for missing 'private' modules should be filled in eventually, I agree,
but there should be a warning that such a module is not intended to be used
directly in a client program because there is no need to use it and the interface
is subject to be changed more frequently than 'public' modules; or some similar hint.
Filling the gaps for private modules, however, is not a small task and the syntactical support
you get from something like JavaDoc is only the trivial part of it.
There is also the (** ... **) comment convention being employed in
standard BB modules. This is close to JavaDoc but I don't know which tool
actually looks at such 'exported' comments.

- Josef

[ReneK]

BB has already an extensive set of conventions regarding the documentation structure;
see 'Documentation Conventions'. It should also fit to CPC subsystems.

Maybe it's one of the gaps, but I just downloaded Alacarte, and aside from the Quick-Start, there is no module docu (accessible via Info->Documentation) here. Same goes for Coco and some of CpC (CpcBeautifier, CpcLangMapper). There's always Quick-Start with an overall explanation, but no documentation that works with marking Module.Procedure and "Documentation" from the context menu.

Helmut adapted all the documents that are affected by the 1.7 changes in a very decent way, for example.

OK, so it seems he is working on getting the collection to conform to the standard documentation. Is that what you are saying?

The docs for missing 'private' modules should be filled in eventually, I agree, but there should be a warning that such a module is not intended to be used directly in a client program because there is no need to use it and the interface is subject to be changed more frequently than 'public' modules; or some similar hint.

Good idea. As I said, those would be documenation stubbs not complete documentations.

This is close to JavaDoc but I don't know which tool actually looks at such 'exported' comments.

I there were such a tool, that's exactly what I wanted. But so far, I know of none.

[Josef Templ]

>> OK, so it seems he is working on getting the collection to conform to the standard documentation. Is that what you are saying?

Not really, the 1.7 changes are changes in the framework itself, not in the CPC subsystem collection.
The collection is more or less unchanged.

- Josef

[Ivan Denisov]

We should return to this important question and find some compromise solution.
I definitely agree:
- with Rene, that undocumented modules should now have documentation
- with Josef, that this documentation should not be easy available to prevent unhermetisation troubles for developing components

I do not like the idea of putting this documentation in the web only. It should be included in distribution in a habitual manner like other documentation.
However there should be barrier of using it and I am suggesting three possible solutions:

1. There should be red warning message on the top of the document "Usage of this interface can make you component hard to support in future and led to unsafe operation!!!".
2. The text of the document can be coloured with light grey, so it is not easy to read, you should first "activate" the documentation by colouring to black
3. We can hide the documentation into folds, and write "This is private interface. Use it only for framework development!"

There is one issue-#35 pending until we come to some team collective decision about the documentation strategy.

[DGDanforth]

We should return to this important question and find some compromise solution.
I definitely agree:
- with Rene, that undocumented modules should now have documentation
- with Josef, that this documentation should not be easy available to prevent unhermetisation troubles for developing components

I do not like the idea of putting this documentation in the web only. It should be included in distribution in a habitual manner like other documentation.
However there should be barrier of using it and I am suggesting three possible solutions:

1. There should be red warning message on the top of the document "Usage of this interface can make you component hard to support in future and led to unsafe operation!!!".
2. The text of the document can be coloured with light grey, so it is not easy to read, you should first "activate" the documentation by colouring to black
3. We can hide the documentation into folds, and write "This is private interface. Use it only for framework development!"

There is one issue-#35 pending until we come to some team collective decision about the documentation strategy.

I like the idea of using a fold.

[Ivan Denisov]

Now I put the DevSelectors documentation without the Folds, because think that it can not be "dangerous". And it is actually not "framework-level" documentation.

But any comments here are still welcome. We need a rule for the documentation we want to be for developing and modification of the framework.

Also, there are many other fixes in the documentation. For example DevDebug "It is not permitted to distribute the full debugger (DevDebug)." This information is not actual any more. It was from times when BB was not open source.

Also, I am suggesting to remove all the references to MacOS from the documentation. BB does not support it, so this can lead to misunderstanding. That do you think about this?

Can we make one big issue for this changes? What are you thinking?

[DGDanforth]

Also, I am suggesting to remove all references to MacOS from the documentation. BB does not support it, so this can lead to misunderstanding. That do you think about this?

It is my distant hope that eventually BB can be released on multiple platforms in (some) uniform systematic manner.
However, since I don't see that happening in the immediate future I would support removal (but saving of) the
documentation concerning MacOS.

-Doug

[Josef Templ]

I would add the DevSelectors docu as a separate issue.
This docu closes a gap and is not a documentation of
an intentionally undocumented low-level module.
So it is really different.

I would create another issue for cleaning up license related stuff.

I don't know how much MacOS stuff is inside the docu and I never cared about it.
Therefore it is OK for me to ignore this aspect for 1.7.

- Josef