🚀 go-pugleaf

In article <RSW.91May23195448@tahiti.cs.brown.EDU>, rsw@cs.brown.EDU (Bob Weiner) writes:
|> In article <9105211847.AA19496@vingmed.no> oaf%pluto%vmsfo.UUCP@NAC.NO (Ole Asbjorn Fadum) writes:
|> 
|> > Hi
|> > 
|> > I wonder if someone work's with some kind of online help ? How is the
|> > easist way of making online help inside IV ?
|> > 
|> > 
|> 
|> Such a capability would be much easier to provide and probably more
|> useful if the key developers of Interviews move the documentation of
|> classes from their set of manual pages, into the actual code.  Then
|> extractor programs could be used to produce in context online help and
|> the associated text for use in the man pages.
|> 
|> I think a large number of people would like this.  It is always
|> disconcerting to come upon code without a thread of documentation
|> inline.  I've often wondered where people pick up such a skill.  Most
|> posters to comp.sources.* have mastered it quite nicely.

Online help is a good thing.

Comments in code can be good.

However, extracting online help from code comments is not an appropriate strategy.
Users need to know how to use software, both through examples and precise semantics.
Code comments are better reserved for implementation notes, and as such are not
intended for users.  One could try to keep user-level information in .h files, but we
have found that is too cumbersome given the current build technology (make).
It is also important for user documentation to be well-formatted; this is hard
to derive automatically from source code.  What would be nice is a hypertext tool
that allowed one to navigate between class interfaces (.h files) and associated semantics/examples (manual).