Re: more comments in HTML doc

From: Pasha Murat (murat@cdfsga.fnal.gov)
Date: Thu Aug 06 1998 - 22:27:17 MEST


Valery Fine writes:
 > On  6 Aug 98 at 11:26, Pasha Murat wrote:
 > 
 > 
 > >  I have one more suggestion.  I believe it would be very nice if
 > >  some 
 > > comments typed in the include files would propagate into
 > > THtml-generated documentation. The case I'm particularly interested
 > > in is given by the following  fragment of an include file:
 > 
 >   There are two points to be taken in account.
 >   The present implementation of Html picks the information for 
 > the HTML page of the "class definition" not from the header file *.h 
 > but from the memory resident RTTI CINT dictionary.
 > 
 >   Been adopted your idea will consume a lot of extra main memory.
 >   Another problem, since this information is supplied by CINT - CINT 
 > should be changed.
 > 
 >    Everything sounds too expansive. Anyway this information is 
 > available via "source code" page (More precise from the *.cxx file 
 > not from *.h, but may be you may adjust your source code comments)
 > 

Hi Valery,
	thanks, I understand your point. However, it wasn't not just my 
idea - I discussed this issue with different people at CDF and we also looked
at what commercial tools are doing. For example, D0 experiment bought 
licence for DOC++ tool, which is essentially the same as THtml class.
The bottom line is that people'd like to have both - 1-2-3 line long comments 
briefly describing the data members and meaning/possible values of the call 
parameters picked from the include file and also more detailed description
of the algorithm taken from the source file.
	Thinking about the technical part of this issue I'd say that I see
many advantages in using header files instead of run-time dictionaries for 
generating the HTML documentation but not the vice versa - it is rather 
difficult to accept the fact that for generating the documentation you have 
at least to generate a shared library first - all the necessary info (.h 
and .cc(.cxx) files) are available without it. 
	So it seems that there is some room for improvement here. Another 
question is that of the priority of this job. Frankly it doesnt' seem to be 
very high. However may be there are volunteers to do it?

		-Pasha



This archive was generated by hypermail 2b29 : Tue Jan 04 2000 - 00:34:35 MET