This is the mail archive of the
gcc@gcc.gnu.org
mailing list for the GCC project.
Re: "Documentation by paper"
- From: Gabriel Dos Reis <gdr at integrable-solutions dot net>
- To: Daniel Berlin <dberlin at dberlin dot org>
- Cc: kenner at vlsi1 dot ultra dot nyu dot edu (Richard Kenner), Joe dot Buck at synopsys dot com, gcc at gcc dot gnu dot org
- Date: 27 Jan 2004 20:58:27 +0100
- Subject: Re: "Documentation by paper"
- Organization: Integrable Solutions
- References: <10401271850.AA29985@vlsi1.ultra.nyu.edu><CAE73078-50FA-11D8-9C84-000A95DA505C@dberlin.org>
Daniel Berlin <dberlin@dberlin.org> writes:
| On Jan 27, 2004, at 1:50 PM, Richard Kenner wrote:
|
| > /**
| > * @brief Search a sequence for a matching sub-sequence.
| > * @param first1 A forward iterator.
| > * @param last1 A forward iterator.
| > * @param first2 A forward iterator.
| > * @param last2 A forward iterator.
| > * @return The first iterator @c i in the range
| > * @p [first1,last1-(last2-first2)) such that @c *(i+N) == @p
| > *(first2+N)
| > * for each @c N in the range @p [0,last2-first2), or @p last1 if no
| > * such iterator exists.
| >
| ...
|
| > This should simply be:
| >
| > /* This function searches a sequence for a matching sub-sequence.
| > FIRST1, LAST1, FIRST2 and LAST2 are allforward iterators.
| > The first iterator J in the range [FIRST1,LAST1-(LAST2-FIRST2))
| > such that
| > *(J+N) == *(FIRST2+N) for each @c N in the range [0,LAST2-FIRST2) is
| > returned, or LAST1 if no such iterator exists. */
|
| > That's a *lot* cleaner and easier to read.
| >
| Maybe for you, but i find that incredibly difficult to read and parse
| compared to the original marked up version, let alone understand.
I far much prefer Richard's version. Simple and clear to read. I've
tried to stay far away from the doxygen business in V3land.
-- Gaby