This is the mail archive of the
mailing list for the GDB project.
Re: FYI: minsyms documentation
On 12/22/11 12:13 PM, Tom Tromey wrote:
Stan> On 12/21/11 6:34 PM, Tom Tromey wrote:
"Stan" == Stan Shebs<firstname.lastname@example.org> writes:
Stan> I'm not liking this idea very much I'm afraid.
I am checking this in on the trunk.
Today I decided to try to document the minsyms API more or less the way
I would like APIs to be documented in general. This patch implements
that; it move documentation from function definitions to minsyms.h, adds
an introductory comment about minsyms there as well, and it rearranges
the header into a more logical order.
Do you mean you want me to back out the patch?
Let me know.
We don't need to be that hasty. :-) I'd like to see more thoughts and
reactions; if everybody else likes it, I won't stand in the way of progress!
Stan> Second, this is potentially a very large change to the sources, but if
Stan> it's incremental, then we get into a confusing situation where some
Stan> files are changed, others are not, and some headers are half-changed
Stan> because they service multiple source files.
This is the present situation.
True, and certainly we should provide some sort of guidance on the point.
One way to look at it is if we assume that the transition to C++ occurs
at some point, what happens to current function head comments? Do they
tend to stay put, as explanation of a method's implementation, or do
they tend to migrate to class definitions in headers? Perhaps method
implementations won't often need head comment blocks at all, as the
interface is documented in headers, and anything interesting in the
implementation is described with inline comments as is is now.