On 4/11/10 10:33 AM, Davi Arnaut wrote:
>
>> Also, it would be great if someone could summarize what are
>> the suggestions, and what are the pros an cons. (Tor?) Otherwise
>> this discussion can go on forever.
>
> I think there is really just one suggestion. In a nutshell, document
> interface in headers, document implementation in source file.
>
A summary of the pros and cons given in the dicussion:
Pros:
- Installed headers (without source file) will have documentation.
- Separation between interface and implementation documentation. Reduced
signal-to-noise ratio: it is possible to generate documentation for a
target audience. That is, interface docs won't be encumbered with
internal details. Assuming there is usually two audiences (users and
implementors) and that implementors can be users (think modular design).
- Wisdom of crowds: it's a somewhat standard practice.
http://tinyurl.com/ydc386c http://tinyurl.com/y8wz2dd
Provides a somewhat better experience (least surprising). In this
case, there aren't significant gains by just being different.
Cons:
- See Monty's remarks.
