"Jeff Garland" <[EMAIL PROTECTED]> writes:
> On Thu, 24 Mar 2005 15:18:42 -0500, David Abrahams wrote
>
>> > 2) I too do not like
>> > special tagged comments in my source code.
>>
>> Well, me neither. That said, you either need to stick special
>> directives in your quickbook source or in your C++ source, or both.
>> Notation to support weaving is just one of those costs that you have
>> to pay in systems like this one. The only alternative is a system
>> with some kind of GUI controls -- which are notation in their own
>> way, after all, but I guess if you always edit with the same tool
>> you can store that data in a separate file.
>
> On the face of it, it would be really nice if special 'tags' in comments were
> not required. But I agree with Dave that some syntax or notational rules are
> required. More below...
>
>> > In that sense, I am not quite fond of Doxygen, in fact.
>>
>> One of the nice things about Synopsis is that if you have a regular
>> commenting style, it can be programmed to understand the meaning of
>> your untagged comments. For example:
>>
>> // This is the documentation
>> // for the function declaration
>> // below it
>> int f();
>
> In my opinion regular comments won't scale for the simple reason that not
> every comment in code is wanted in documentation (maintainer notes, todo, bug
> references).
It's simple to use conventions to exclude those:
// This is docs for f()
int f();
// This comment is not supposed to show up in the docs.
// This one is docs for g().
int g();
It works for me in real life.
I'm not sure that most of those things you mention belong in comments
in code, FWIW. I would not be inclined to dribble that stuff around;
it harms readability. That's the opposite of what comments should do.
> Also, you need a bit more meaty function to see some other
> issues in extraction. For example documentation of parameters, return values,
> and exceptions.
No, you don't need ugly tags. Just adopt a regular convention that
humans and computers can understand.
> Also, depending on your sophistication you might like to
> separation of user docs from maintainer docs. For example:
> //@ingroup user_docs {
> // This is the documentation
> // for the function declaration
> // below it
> // @param bar description of bar
> // @return 0 if foo and bar are equal, -1 if bar is less
> // @param foo description of foo
> // @exception my_exception - throw when either string is empty
> // }
> //@ingroup maintainer_docs {
> // Docs for the maintainer only...
> // }
> int f(std::string bar, std::string foo);
> Some consider this ugly.
Indeed.
// This is the documentation
// for the function declaration
// below it
// :bar: description of bar
// :foo: description of bar
//
// RETURNS: zero if foo and bar are equal,
// -1 if bar is less
//
// THROWS: my_exception when either string is empty
//
// MAINTAINER NOTES: Docs for the maintainer only
//
int f(std::string bar, std::string foo);
is beautiful. I was writing my comments almost exactly like this
before I ever thought about automated extraction.
> I consider it a practical way to keep things that
> need to be together in the same place -- code and docs.
The beautiful can be practical, too. Why not have both?
> Once you really start thinking about what you want to do with
> documenting in code these more complex issues come up.
Please, I'm not as naive as you seem to think. I "really started
thinking about what I want to do with documenting code" about 15-20
years ago and haven't stopped since.
> So I think to be 'against doxygen' on this point is to be
> against practicality.
No, it's to be against ugliness and unreadability for the people who
actually look at the code. There's no reason you can't have
practicality and beauty.
> The parser and programmer need to be able to distiguish
> which text documents what elements. Is there possibly a cleaner
> syntax?
Yes.
> Possibly. However, there are are large number of programmers that understand
> the doxygen/javadoc tag-based approach.
It's hideous. IMO there's little excuse for such a design other than
lack of imagination or laziness. Sorry to come off so judgementally,
but it's not your work so I feel free to say what I think. This
design has offended me since the moment I saw it. When I saw it in
use for Java I thought "oh, well, at least it's just a Java thing" and
was really dismayed when it started to show up in C++.
> So I think it's great that Synopsys will support different options,
> but I suspect even with Synopsys sophisticated docs will use
> tagging.
Only if nobody implements something better.
> See: http://synopsis.fresco.org/docs/Tutorial/comments.html
What's your point? I know Synopsis supports the Javadoc convention
OOTB. Doesn't make it a good thing.
--
Dave Abrahams
Boost Consulting
www.boost-consulting.com
-------------------------------------------------------
SF email is sponsored by - The IT Product Guide
Read honest & candid reviews on hundreds of IT Products from real users.
Discover which products truly live up to the hype. Start reading now.
http://ads.osdn.com/?ad_id=6595&alloc_id=14396&op=click
_______________________________________________
Boost-docs mailing list
[email protected]
Unsubscribe and other administrative requests:
https://lists.sourceforge.net/lists/listinfo/boost-docs
