On 26 Jun 1997, Terrence Brannon wrote:
> Actually, putting all of the documentation for a complex member
> function at the top is very unhelpful to understand it.
Well, it depends on your documentation style, I guess. If you
want to give a brief description for a member function then ROOT
Doc should be OK. If you want to describe each line of code then
you can give an access to your source code tree (like we do). But
if you want to have detailed description and you don't want to
show source code - then you get 'unhelpful and hard to understand
documentation', as you said.
> It is much
> better that each complex part have documentation and preferably that
> each complex part be a "fold" in a folded Emacs buffer.
How do you think to collect and connect those parts? This is
not possible unless I invent special language and I force you to
change your existing 300,000 lines of code to be able to use it.
> Therefore, preferably, ROOTdoc would pick commentary out throughout a
> member function as opposed to just the top.
There are other comments in the code which we can not call
'the documentation' and maybe we don't want to see them printed
out.
We wanted to create a simple tool (and flexible enough) which
will require no major changes for existing C++ code but still be
able to generate useful documentation in several formats. We are
not far away from that.
Next version will no longer require ClessDef() macro in your
header files and will offer output in html format, unix man format,
FrameMaker, PageMaker, plain text, etc. Very likely will come
as stand-alone program.
-------------------------------------------------------
Nenad BUNCIC email: Nenad.Buncic@cern.ch
CERN, PPE Division/NA49 phone: (+41.22.76)76462,
CH-1211 Geneva 23 (+41.22.76)74921
SWITZERLAND fax: (+41.22.76)77910
-------------------------------------------------------
This archive was generated by hypermail 2b29 : Tue Jan 04 2000 - 00:26:19 MET