Building documentation from comments

Building documentation from comments

[Victor Porton]

Hi! Sorry if some of you receive this my message second time:
my news was misconfigured.

I want to extract comments from Booch library and make HTML docs.

I tries to use AdaBrowse, but it doesn't do it well (skips some
comments entirely and it seems impossible to tune it with
configuration file to include all comments.)

All docs for AdaDoc are in French, which I don't know.

Any other programs for extracting comments from Ada sources?

Re: Building documentation from comments

[Ira Baxter]

The DMS Software Reengineering Toolkit is generalized
compiler technology for parsing/analyzing/transforming/prettyprinting
many source languages, including Ada.
See http://www.semdesigns.com/Products/DMS/DMSToolkit.html.

It could be very easily configured to extract arbitrary information
from Ada comments.  Its Ada83/95 parser builds a full
syntax tree decorated with the comment text.  Walking
over the tree can visit all the comments, what you do with
them after than can be arbitrary.

A "trivial"  application is to print the source code,
with the comments, nicely formatted.
See http://www.semdesigns.com/Products/Formatters/AdaFormatterExample.html.

--
Ira D. Baxter, Ph.D., CTO   512-250-1018
Semantic Designs, Inc.      www.semdesigns.com


"Victor Porton" <porton@home.porton.narod.ru> wrote in message
news:3dc7f605$0$303$bed64819@news.gradwell.net...
> Hi! Sorry if some of you receive this my message second time:
> my news was misconfigured.
>
> I want to extract comments from Booch library and make HTML docs.
>
> I tries to use AdaBrowse, but it doesn't do it well (skips some
> comments entirely and it seems impossible to tune it with
> configuration file to include all comments.)
>
> All docs for AdaDoc are in French, which I don't know.
>
> Any other programs for extracting comments from Ada sources?

Re: Building documentation from comments

[Caffeine Junky]

On Tue, 05 Nov 2002 11:41:27 -0500, Victor Porton wrote:

> Hi! Sorry if some of you receive this my message second time: my news
> was misconfigured.
> 
> I want to extract comments from Booch library and make HTML docs.
> 
> I tries to use AdaBrowse, but it doesn't do it well (skips some comments
> entirely and it seems impossible to tune it with configuration file to
> include all comments.)
> 
> All docs for AdaDoc are in French, which I don't know.
> 
> Any other programs for extracting comments from Ada sources?
 

Check out FunnelWeb or one of the other many Literate Programming tools
out there on the net.

Caffiene Junky

Re: Building documentation from comments

[Victor Porton]

In article <3dc86f81$1@giga.realtime.net>,
	"Ira Baxter" <idbaxter@semdesigns.com> writes:
> The DMS Software Reengineering Toolkit is generalized
> compiler technology for parsing/analyzing/transforming/prettyprinting
> many source languages, including Ada.
> See http://www.semdesigns.com/Products/DMS/DMSToolkit.html.

I cannot find on your site anything about downloading/ordering!

Re: Building documentation from comments

[Victor Porton]

In article <ox%x9.27059$ar4.112591@sccrnsc03>,
	Caffeine Junky <nospam@hotmail.com> writes:
> On Tue, 05 Nov 2002 11:41:27 -0500, Victor Porton wrote:
> 
>> Hi! Sorry if some of you receive this my message second time: my news
>> was misconfigured.
>> 
>> I want to extract comments from Booch library and make HTML docs.
> 
> Check out FunnelWeb or one of the other many Literate Programming tools
> out there on the net.

FunnelWeb is not what I want at all: I want hyper-cross-referenced
(and desirably pretty printed Ada) source, while FunnelWeb does not
"know" Ada.

P.S. May be the best solution would be if I would find time to modify
Booch source in such the way that it would become fully compatible with
AdaBrowse. Is Boch author here? Would you include my changes in the
next release and continue to follow my policy for compatibility with
AdaBrowse?

Re: Building documentation from comments

[David C. Hoos]

Have you considered the perl script that comes with gnat -- gnathtml.pl?
----- Original Message ----- 
From: "Victor Porton" <porton@ex-code.com>
Newsgroups: comp.lang.ada
To: <comp.lang.ada@ada.eu.org>
Sent: Wednesday, November 06, 2002 2:30 AM
Subject: Re: Building documentation from comments


> In article <ox%x9.27059$ar4.112591@sccrnsc03>,
> Caffeine Junky <nospam@hotmail.com> writes:
> > On Tue, 05 Nov 2002 11:41:27 -0500, Victor Porton wrote:
> > 
> >> Hi! Sorry if some of you receive this my message second time: my news
> >> was misconfigured.
> >> 
> >> I want to extract comments from Booch library and make HTML docs.
> > 
> > Check out FunnelWeb or one of the other many Literate Programming tools
> > out there on the net.
> 
> FunnelWeb is not what I want at all: I want hyper-cross-referenced
> (and desirably pretty printed Ada) source, while FunnelWeb does not
> "know" Ada.
> 
> P.S. May be the best solution would be if I would find time to modify
> Booch source in such the way that it would become fully compatible with
> AdaBrowse. Is Boch author here? Would you include my changes in the
> next release and continue to follow my policy for compatibility with
> AdaBrowse?
> _______________________________________________
> comp.lang.ada mailing list
> comp.lang.ada@ada.eu.org
> http://ada.eu.org/mailman/listinfo/comp.lang.ada
> 

Re: Building documentation from comments

[Larry Kilgallen]

In article <3dc8c80b$0$300$bed64819@news.gradwell.net>, porton@ex-code.com (Victor Porton) writes:
> In article <3dc86f81$1@giga.realtime.net>,
> 	"Ira Baxter" <idbaxter@semdesigns.com> writes:
>> The DMS Software Reengineering Toolkit is generalized
>> compiler technology for parsing/analyzing/transforming/prettyprinting
>> many source languages, including Ada.
>> See http://www.semdesigns.com/Products/DMS/DMSToolkit.html.
> 
> I cannot find on your site anything about downloading/ordering!

Or pricing !

Re: Building documentation from comments

[Victor Porton]

In article <mailman.1036575602.31424.comp.lang.ada@ada.eu.org>,
	"David C. Hoos" <david.c.hoos.sr@ada95.com> writes:
> Have you considered the perl script that comes with gnat -- gnathtml.pl?

OK, it is near to what I need. But it always insert a big copyright
comment at beginning of every HTML file, it would be good in a next
version of GNAT add possibility to remove this comment by gnathtml.

>> > On Tue, 05 Nov 2002 11:41:27 -0500, Victor Porton wrote:
>> > 
>> >> I want to extract comments from Booch library and make HTML docs.

Re: Building documentation from comments

[Marc A. Criley]

Victor Porton wrote:

> P.S. May be the best solution would be if I would find time to modify
> Booch source in such the way that it would become fully compatible with
> AdaBrowse. Is Boch author here? Would you include my changes in the
> next release and continue to follow my policy for compatibility with
> AdaBrowse?

This is the approach I've taken with some brand new Ada that I'm
writing.  I'm trying AdaBrowse out as a documentation aid, and am
finding that by tweaking the configuration file a bit, and then ensuring
my comments are in the right locations, that the docs are coming out
pretty good.

I find it most effective to write some code and associated comment docs,
then run AdaBrowse and review the output, to ensure that everything is
being properly grouped together.  I don't find the comment positioning
requirements too onerous, it's certainly no worse than, say, having to
do manual indenting of source code statements.

Marc A. Criley
Quadrus Corporation
www.quadruscorp.com

Re: Building documentation from comments

[Ira Baxter]

In general, http://www.semdesigns.com/Products/index.html, see top of page.

The DMS Toolkit is quoted on request, as it comes with lots of options.

--
Ira D. Baxter, Ph.D., CTO   512-250-1018
Semantic Designs, Inc.      www.semdesigns.com

"Larry Kilgallen" <Kilgallen@SpamCop.net> wrote in message
news:kf+gYrIb5Xaj@eisner.encompasserve.org...
> In article <3dc8c80b$0$300$bed64819@news.gradwell.net>, porton@ex-code.com
(Victor Porton) writes:
> > In article <3dc86f81$1@giga.realtime.net>,
> > "Ira Baxter" <idbaxter@semdesigns.com> writes:
> >> The DMS Software Reengineering Toolkit is generalized
> >> compiler technology for parsing/analyzing/transforming/prettyprinting
> >> many source languages, including Ada.
> >> See http://www.semdesigns.com/Products/DMS/DMSToolkit.html.
> >
> > I cannot find on your site anything about downloading/ordering!
>
> Or pricing !

Re: Building documentation from comments

[Ira Baxter]

"Victor Porton" <porton@ex-code.com> wrote in message
news:3dc8d6e1$0$301$bed64819@news.gradwell.net...

>  I want hyper-cross-referenced
> (and desirably pretty printed Ada) source, while FunnelWeb does not
> "know" Ada.

I think you'd be very interested in an Ada analogue to
our Java Browser, which combines JavaDoc + "hyper cross referenced" Java.
See http://www.semdesigns.com/Products/Formatters/JavaHTMLizer.html.
The cross references are accurate according to the language scoping rules,
not just "string match", so this is really useful on big systems.

You are right, to do this, you ideally need a tool that "knows" Ada in the
sense
of being able to resolve symbols the same way as the Ada compiler does.
While we have full Ada parsers, we do not yet have Ada symbol table
information.    We could certainly build it with enough encouragement.

--
Ira D. Baxter, Ph.D., CTO   512-250-1018
Semantic Designs, Inc.      www.semdesigns.com

Re: Building documentation from comments

[Ted Dennison]

porton@ex-code.com (Victor Porton) wrote in message news:<3dc90146$0$308$bed64819@news.gradwell.net>...
> In article <mailman.1036575602.31424.comp.lang.ada@ada.eu.org>,
> 	"David C. Hoos" <david.c.hoos.sr@ada95.com> writes:
> > Have you considered the perl script that comes with gnat -- gnathtml.pl?
> 
> OK, it is near to what I need. But it always insert a big copyright
> comment at beginning of every HTML file, it would be good in a next
> version of GNAT add possibility to remove this comment by gnathtml.

A nit: I'd say that I have no promlem with ACT doing that with their
commercial compiler. You may have an argument with the version in the
gcc baseline (if gnathtml.pl is in the gcc baseline yet). If so,
remove the perl source that does that yourself and see if they'll let
you check it in. :-)

Re: Building documentation from comments

[Victor Porton]

In article <4519e058.0211060724.9b9a26b@posting.google.com>,
	dennison@telepath.com (Ted Dennison) writes:
> porton@ex-code.com (Victor Porton) wrote in message news:<3dc90146$0$308$bed64819@news.gradwell.net>...
>> In article <mailman.1036575602.31424.comp.lang.ada@ada.eu.org>,
>> 	"David C. Hoos" <david.c.hoos.sr@ada95.com> writes:
>> > Have you considered the perl script that comes with gnat -- gnathtml.pl?
>> 
>> OK, it is near to what I need. But it always insert a big copyright
>> comment at beginning of every HTML file, it would be good in a next
>> version of GNAT add possibility to remove this comment by gnathtml.
> 
> A nit: I'd say that I have no promlem with ACT doing that with their
> commercial compiler. You may have an argument with the version in the
> gcc baseline (if gnathtml.pl is in the gcc baseline yet). If so,
> remove the perl source that does that yourself and see if they'll let
> you check it in. :-)

You misunderstood: gnathtml does not insert its own copyright,
I just want removal extra comments from .ads files :-)

Re: Building documentation from comments

[Stephen Leake]

porton@ex-code.com (Victor Porton) writes:

> You misunderstood: gnathtml does not insert its own copyright,
> I just want removal extra comments from .ads files :-)

Removing copyright and license notices is normally _not_ permitted by
the license, so you should _not_ do that.

Now, if you could automatically remove all the comments that are
_wrong_, that would be useful :).

-- 
-- Stephe

Re: Building documentation from comments

[Simon Wright]

porton@ex-code.com (Victor Porton) writes:

> P.S. May be the best solution would be if I would find time to
> modify Booch source in such the way that it would become fully
> compatible with AdaBrowse. Is Boch author here? Would you include my
> changes in the next release and continue to follow my policy for
> compatibility with AdaBrowse?

I guess that depends on how much work it is, for how much gain. At the
moment I am having trouble with AdaBrowse. My fault for trying to
compile with GCC 3.3, of course.

Re: Building documentation from comments

[Simon Wright]

porton@ex-code.com (Victor Porton) writes:

> In article <mailman.1036575602.31424.comp.lang.ada@ada.eu.org>,
> 	"David C. Hoos" <david.c.hoos.sr@ada95.com> writes:
> > Have you considered the perl script that comes with gnat -- gnathtml.pl?
> 
> OK, it is near to what I need. But it always insert a big copyright
> comment at beginning of every HTML file, it would be good in a next
> version of GNAT add possibility to remove this comment by gnathtml.

It always reproduces the big copyright comment that is in the source
file!

Not sure about the ethics of removing other folks' copyright notices.

RE: Building documentation from comments

[Robert C. Leif]

Returning to the title of this thread, "Building documentation from
comments", one might wish to replace the comment with the equivalent of
an XML Annotation or Annotations.Documentation. The Ada translation of
the XML model would be to create an Annotations Package and a
Documentation child package.  These packages would included an
instantiation of a bounded string type of the appropriate size to be a
Copyright(Copyright_Bd). Each package then can have a group of
annotations that include the Copyright_Bd, Author(s) Revision_Dates etc.
These can even have default values or when appropriate point to a URL.
The use of a URL has the advantage of permitting direct access to the
text of large legal documents without cluttering the code.
Bob Leif

Re: Building documentation from comments

[Victor Porton]

In article <x7vvg3914ma.fsf@smaug.pushface.org>,
	Simon Wright <simon@pushface.org> writes:
> porton@ex-code.com (Victor Porton) writes:
> 
>> P.S. May be the best solution would be if I would find time to
>> modify Booch source in such the way that it would become fully
>> compatible with AdaBrowse. Is Boch author here? Would you include my
>> changes in the next release and continue to follow my policy for
>> compatibility with AdaBrowse?
> 
> I guess that depends on how much work it is, for how much gain. At the

We just need to develop a simple "standard" of commenting compatible
with AdaBrowse and follow it.

The main problem with comments in the current Booch is that some of
these have empty lines within them, but these should be replaced by
"--" lines (with nothing after "--"). Comments also should be a little 
reordered. It is all.

Re: Building documentation from comments

[Victor Porton]

In article <x7vr8dx14iu.fsf@smaug.pushface.org>,
	Simon Wright <simon@pushface.org> writes:
> porton@ex-code.com (Victor Porton) writes:
> 
> It always reproduces the big copyright comment that is in the source
> file!
> 
> Not sure about the ethics of removing other folks' copyright notices.

Just removing such notices for local use (not for distributing) to reduce
needed scrolling in the Web browser :-)

Surely distributing files with removed copyright is immoral (if not 
used for just exposition).

Re: Building documentation from comments

[Michael Erdmann]

I have build some time ago a tool which generates out 
the the comments doocbook documents. This generation is 
based upon some heuritics, e.g.

XXXXXXXXXX
==========

Is proably a dscription and so on. But the problem
is to get the people to follow at least these minimal
resquirements on the structure of the comments.

Michael


Victor Porton wrote:

> In article <x7vr8dx14iu.fsf@smaug.pushface.org>,
> Simon Wright <simon@pushface.org> writes:
>> porton@ex-code.com (Victor Porton) writes:
>> 
>> It always reproduces the big copyright comment that is in the source
>> file!
>> 
>> Not sure about the ethics of removing other folks' copyright notices.
> 
> Just removing such notices for local use (not for distributing) to reduce
> needed scrolling in the Web browser :-)
> 
> Surely distributing files with removed copyright is immoral (if not
> used for just exposition).