On Fri, 25 Mar 2005 09:48:11 -0500, David Abrahams wrote > 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.
Sure, but is this implicit syntax clear for someone that needs to maintain your code five years from now? Lots of implicit rules require the maintainer to know the rules -- I'd like to be able to figure out the rules just by reading the code. > 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. Ok, that contradicts your point below. But regardless there's at least one programmer (me) that wants to maintain all this with the code ;) > No, you don't need ugly tags. Just adopt a regular convention that > humans and computers can understand. > > ...snip "ugly example"... > > > 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. Not to be difficult, but sorry, I don't really like it as you wrote it. If you uncapitalized the titles it would be much better -- all caps is really distracting to me. I like the fact that there is no '@' syntax for identifying a tag, but there's still a tag to identify the sections. In the case of :bar:, if we didn't have the discussion context I'm not sure it would be obvious what it meant. > > 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? No disagreement, but there are many programmers that don't have your refined eye for beauty. Apparently I'm one of them because I never really had a negative reaction to javadoc syntax. > 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. I know you aren't -- my comments weren't only directed toward you. It wasn't clear that everyone would understand from the context of the discussion that the example case was ignoring much of the complexity associated with more sophisticated code documentation schemes. > > 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. I'll be first in line when a viable replacement appears. In the meantime I'll use the available tools. > > 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++. No offense taken -- I was already aware of your strong feelings on the subject. > > 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. The point is that practical documentation extraction requires a syntax. Like it or not, the javadoc conventions are widely used and we shouldn't preclude them. Jeff ------------------------------------------------------- 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
