Eric Niebler wrote:
Deane Yang wrote:
Eric Niebler wrote:
Once again, the "before":
http://tinyurl.com/ho2a3
and the "after":
http://tinyurl.com/fh43h
Others are welcome to jump into this discussion at any time. :-)
I don't have any useful suggestions, but I find both versions visually
confusing, because, despite the capitalization, the "Requires",
"Returns", and "Throws" look too much like they're part of the
Parameters list.
An extremely minor quibble is that I would also prefer that "Requires"
be replaced by "Requirements".
Maybe (but I'm not sure) "Requires", "Returns", and "Throws" should be
at the same level as "Parameters"?
I tend to agree. Is this better?
http://tinyurl.com/j4y4s
I prefer the first 'after' over the 'before'. I find the breaks in the
parameter list distracting and that they provide for less readability in
the 'before'.
I'll have to note, however, that the different widths look ugly in the
first 'after' and don't actually convey any information: is it a
formatting glitch? is the intent to have two independent tables? I think
these issues would be better addressed with either some text or some
more obvious visual separation of the two tables. As David Abrahams
noted the columns might as well just happen to have the same width.
All in all, I prefer the second 'after' in your last link above. I think
it solves all issues simply and nicely!
It uses a nested table. Are there browsers out there that don't handle
that? Looks OK with Firefox and IE6.
Looking good on firefox, epiphany (firefox-based, but still...),
konqueror and opera, all on linux. Konqueror centers 'Parameters'
vertically and has some more formatting differences, but seems to handle
it well.
I wouldn't vouch on it, but it is my impression that nested tables are
quite ubiquituous as a formatting and design element so as to make them
widely supported. Again, I'm no expert on the matter.
Maybe "Requires" should really be "Preconditions". After all, we already
have "Postconditions".
To me, I tend to prefer "Preconditions", but as long as the use is
consistent, any would do.
On a totally unrelated note... Although the semantics look obvious, you
should also add 'str' to the parameters list and maybe add some notes on
the use `Char const * begin`. Also what is the rationale for singling
out std::basic_string (and Char const *) instead of going for the more
general Range concept? (Fwiw, I'm pursuing a Range-based interface for
Spirit, http://tinyurl.com/npvnz )
Best regards,
João
-------------------------------------------------------
This SF.Net email is sponsored by xPML, a groundbreaking scripting language
that extends applications into web and mobile media. Attend the live webcast
and join the prime developer group breaking into this new coding territory!
http://sel.as-us.falkag.net/sel?cmd=lnk&kid=110944&bid=241720&dat=121642
_______________________________________________
Boost-docs mailing list
[email protected]
Unsubscribe and other administrative requests:
https://lists.sourceforge.net/lists/listinfo/boost-docs
