Experiences

The result (eternally in construction) of this effort may be looked at at www.cs.vu.nl/~eliens/online/hush Clearly, as I will indicate in the conclusions, my initial goals have not all been realized. As concerns the effort involved, apart from the actual annotation, which is minimal due to the use of the aforementioned tools, creating documentation takes a lot of time. Not only in terms of CPU time, but also to see whether the documentation is right, or better adequate in relation to the investment of effort.

You need patience -- on a Sparc Ultra 167 (64MB)

70 MB of documentation -- more than 3 * source
processing time -- over 5 hours
'brute force reverse engineering' -- uniformly
localisation -- the bar takes time
virtual links -- where do I place the source

slide: Experiences

As concerns the result, brute force reverse engineering turns our to be somehat insatisfactory. or an art I'll have to learn.

The localization of documents, that is the indication of their position in the source tree seems to be useful as a point of reference. But creating the bar, including the indexes to the various kinds of (code) documentation takes time.

As a programmer, one cannot wait for it (that is the documentation tools) to finish. More generally speaking, there is clearly a clash of perspectives here. The organisation of the code from the perspective of the programmer may radically differ from the organisation which is most desirable from the perspective of documentation!

Some leverage for this problem can be provided by wiring in support for 'virtual links' in the filters themselves. But still, the clash is there. An optimal solution is hard to find.