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). Also, you need a bit more meaty function to see some other
issues in extraction. For example documentation of parameters, return values,
and exceptions. 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. I consider it a practical way to keep things that
need to be together in the same place -- code and docs. Once you really start
thinking about what you want to do with documenting in code these more complex
issues come up. So I think to be 'against doxygen' on this point is to be
against practicality. The parser and programmer need to be able to distiguish
which text documents what elements. Is there possibly a cleaner syntax?
Possibly. However, there are are large number of programmers that understand
the doxygen/javadoc tag-based approach. So I think it's great that Synopsys
will support different options, but I suspect even with Synopsys sophisticated
docs will use tagging.
See: http://synopsis.fresco.org/docs/Tutorial/comments.html
Bringing this back to Literate programming, I think I can see arguments for
both the include and inline approaches that have been outlined. I haven't
every used literate programming tools, but I'm interested in trying it out :-)
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
