[RFC] Stop putting function comments in foo.h

[RFC] Stop putting function comments in foo.h

[Doug Evans]

Hi.

I'd like to start a discussion.
With doxygen is there still as much value to putting function comments
in foo.h instead of foo.c?

I ask because every time I find a "See foo.h." comment I get depressed
and disappointed.  They're just getting in my way, and I'm wondering
if it's just me.

Re: [RFC] Stop putting function comments in foo.h

[Gerhard Gappmeier]

On Saturday, March 15, 2014 12:45:41 PM Doug Evans wrote:
> Hi.
> 
> I'd like to start a discussion.
> With doxygen is there still as much value to putting function comments
> in foo.h instead of foo.c?
> 
> I ask because every time I find a "See foo.h." comment I get depressed
> and disappointed.  They're just getting in my way, and I'm wondering
> if it's just me.
It's not just you ;-)

Hi had this discussion several times inside my company.
IMO the only valid reason for having the doxygen comments in the header file 
is when you are doing binary distributions with header files and libraries.
This is not the case for Open Source.

If code is distributed it makes more sense to have the comments in the source 
file. Here you need the comments as developer when debugging through the code, 
changing it, or just reviewing it. It annoys me to switch to the header file 
to see what a function is doing. Another advantage of doing so is that the 
header file stays clean if you want to get a quick overview of what functions 
are available.

But that's my opinion and I'm sure other people will have other opinions ;-)

Re: [RFC] Stop putting function comments in foo.h

[Yao Qi]

On 03/16/2014 03:45 AM, Doug Evans wrote:
> Hi.
> 
> I'd like to start a discussion.
> With doxygen is there still as much value to putting function comments
> in foo.h instead of foo.c?
> 
> I ask because every time I find a "See foo.h." comment I get depressed
> and disappointed.  They're just getting in my way, and I'm wondering
> if it's just me.
> 

No, it isn't.  I dislike the "See foo.h" comment either.  Since we had
all source code available, it is convenient to read function comments in
foo.c when we are editing it.

-- 
Yao (齐尧)

Re: [RFC] Stop putting function comments in foo.h

[Joel Brobecker]

> I'd like to start a discussion.
> With doxygen is there still as much value to putting function comments
> in foo.h instead of foo.c?
> 
> I ask because every time I find a "See foo.h." comment I get depressed
> and disappointed.  They're just getting in my way, and I'm wondering
> if it's just me.

I have a preference, but only a slight one, towards putting the comments
in the .c file.

-- 
Joel

Re: [RFC] Stop putting function comments in foo.h

[Sergio Durigan Junior]

On Saturday, March 15 2014, Doug Evans wrote:

> I ask because every time I find a "See foo.h." comment I get depressed
> and disappointed.  They're just getting in my way, and I'm wondering
> if it's just me.

No, it's not just you (though I am now accustomed to this practice and
almost don't bother anymore...).

-- 
Sergio

Re: [RFC] Stop putting function comments in foo.h

[Pedro Alves]

On 03/15/2014 07:45 PM, Doug Evans wrote:
> I'd like to start a discussion.
> With doxygen is there still as much value to putting function comments
> in foo.h instead of foo.c?

IMO, yes.  And IMO doxygen here is a red herring.
I actually don't see myself looking at doxygen docs
much.  Doxygen is supposed to be an aid, there should be no
requirement to build the doxygen docs to be able to understand
gdb's sources, right?

IMO, a module's API documentation should be in its header file, as
that's where the module's "public" contract is defined.
Needing to peek at the module's implementation feels wrong to me.
If the function's documentation isn't clear without looking
at the function's body, something is already wrong with
the comment.

> I ask because every time I find a "See foo.h." comment I get depressed
> and disappointed.  They're just getting in my way, and I'm wondering
> if it's just me.

Whenever I look at a header file that doesn't document its
functions' interfaces (and often doesn't even list the
parameter names), I get depressed and disappointed.  I'm
wondering if it's just me.  :-)

-- 
Pedro Alves

Re: [RFC] Stop putting function comments in foo.h

[DJ Delorie]

Pedro Alves <palves@redhat.com> writes:
> Whenever I look at a header file that doesn't document its
> functions' interfaces (and often doesn't even list the
> parameter names), I get depressed and disappointed.  I'm
> wondering if it's just me.  :-)

Speaking from the "someone who uses the API but doesn't understand the
source tree" point of view, it's usually a lot easier to discover an API
through the header files, and that's where I expect to find some
documentation about the API.

The only time that documentation-in-source works is when there's a
strict one-to-one mapping of headers to sources, else finding the
documentation becomes yet another task to hurdle.

Also, I've yet to find a doxygen doc set that adds any value over just
commenting the headers.

Also, IMHO there should be *two* sets of in-source docs: the headers
should have comments suitable for users of each API, and the source
should have comments relevent to those editing the implementation.

Re: [RFC] Stop putting function comments in foo.h

[Stan Shebs]

On 3/17/14 9:07 AM, Pedro Alves wrote:
> On 03/15/2014 07:45 PM, Doug Evans wrote:
>> I'd like to start a discussion.
>> With doxygen is there still as much value to putting function comments
>> in foo.h instead of foo.c?
> 
> IMO, yes.  And IMO doxygen here is a red herring.
> I actually don't see myself looking at doxygen docs
> much.  Doxygen is supposed to be an aid, there should be no
> requirement to build the doxygen docs to be able to understand
> gdb's sources, right?

I think that's the right viewpoint.  Doxygen normally glues .h and
.c comment blocks into a single documentation node, which nicely
finesses the whole question of where to record API info, but even
so it seems a bit sloppy for us to not make a decision on .h vs .c.

> IMO, a module's API documentation should be in its header file, as
> that's where the module's "public" contract is defined.
> Needing to peek at the module's implementation feels wrong to me.
> If the function's documentation isn't clear without looking
> at the function's body, something is already wrong with
> the comment.

I've flip-flopped on this so many times...

While it seems most logical to have the API documentation in the .h
file, in actual practice the "see foo.h" comments seem awkward and
unhelpful.  It's matched only by the possibility of having no comment
block at all, since many functions in our API have uninteresting bodies.

Going the other way has its own issues, for instance only function and
variable documentation gets to be in a .c file, structs and enums and
macros have to stay in the .h anyway.

At the moment I'm leaning to API in .h, and put down the "see" comments
as one of the many minor irritations in the C programmer's life. :-)

>> I ask because every time I find a "See foo.h." comment I get depressed
>> and disappointed.  They're just getting in my way, and I'm wondering
>> if it's just me.
> 
> Whenever I look at a header file that doesn't document its
> functions' interfaces (and often doesn't even list the
> parameter names), I get depressed and disappointed.  I'm
> wondering if it's just me.  :-)

One of the potential uses for Doxygen is that it has ways to dump
raw info about the sources, and we could use that to build things
like progress meters - identify the 10 most-used functions that are
undocumented and write comments for those, then do the next 10, etc.
Right now it's just the large amorphous need, where fixing it feels
like trying to empty the ocean with a teaspoon. :-)

Stan
stan@codesourcery.com

Re: [RFC] Stop putting function comments in foo.h

[Ricard Wanderlof]

>>> I ask because every time I find a "See foo.h." comment I get depressed
>>> and disappointed.  They're just getting in my way, and I'm wondering
>>> if it's just me.
>>
>> Whenever I look at a header file that doesn't document its
>> functions' interfaces (and often doesn't even list the
>> parameter names), I get depressed and disappointed.  I'm
>> wondering if it's just me.  :-)

One solution would be to simply duplicate the documentation in both the .c 
and .h files. Sure, it's duplicated text, and there's always the 
possibility that they'll get out of sync with each other, but at least 
we're putting the burdon on whoever is writing the code, not whoever is 
reading it, which makes sense since the code will be read many more times 
than it is (re)written.

/Ricard
-- 
Ricard Wolf Wanderlöf                           ricardw(at)axis.com
Axis Communications AB, Lund, Sweden            www.axis.com
Phone +46 46 272 2016                           Fax +46 46 13 61 30

Re: [RFC] Stop putting function comments in foo.h

[Doug Evans]

On Mon, Mar 17, 2014 at 9:07 AM, Pedro Alves <palves@redhat.com> wrote:
> IMO, a module's API documentation should be in its header file, as
> that's where the module's "public" contract is defined.
> Needing to peek at the module's implementation feels wrong to me.
> If the function's documentation isn't clear without looking
> at the function's body, something is already wrong with
> the comment.

It use to be that M-. took me to the function definition and its documentation.

I'm curious what other emacs+etags users do now.

Re: [RFC] Stop putting function comments in foo.h

[Doug Evans]

On Tue, Mar 18, 2014 at 8:59 AM, Doug Evans <dje@google.com> wrote:
> On Mon, Mar 17, 2014 at 9:07 AM, Pedro Alves <palves@redhat.com> wrote:
>> IMO, a module's API documentation should be in its header file, as
>> that's where the module's "public" contract is defined.
>> Needing to peek at the module's implementation feels wrong to me.
>> If the function's documentation isn't clear without looking
>> at the function's body, something is already wrong with
>> the comment.
>
> It use to be that M-. took me to the function definition and its documentation.
>
> I'm curious what other emacs+etags users do now.

fwiw, I'd REALLY like an answer to this.

M-. worked great before people started moving function comments to headers.
I can be looking at any function in the source, put the cursor over
its name, M-. RET, and voila!  I'm reading the function's comment or I
I can begin hacking/reading its implementation.

People are breaking a common existing practice without offering a
replacement.  Why isn't that "Not cool."?
If I'm missing something I'll happily document it in the wiki, augment
Makefile's, or whatever.
I just want to continue to be able to hack on gdb as easily as I could
before people started doing this.

Re: [RFC] Stop putting function comments in foo.h

[Doug Evans]

Doug Evans writes:
 > On Tue, Mar 18, 2014 at 8:59 AM, Doug Evans <dje@google.com> wrote:
 > > On Mon, Mar 17, 2014 at 9:07 AM, Pedro Alves <palves@redhat.com> wrote:
 > >> IMO, a module's API documentation should be in its header file, as
 > >> that's where the module's "public" contract is defined.
 > >> Needing to peek at the module's implementation feels wrong to me.
 > >> If the function's documentation isn't clear without looking
 > >> at the function's body, something is already wrong with
 > >> the comment.
 > >
 > > It use to be that M-. took me to the function definition and its documentation.
 > >
 > > I'm curious what other emacs+etags users do now.
 > 
 > fwiw, I'd REALLY like an answer to this.
 > 
 > M-. worked great before people started moving function comments to headers.
 > I can be looking at any function in the source, put the cursor over
 > its name, M-. RET, and voila!  I'm reading the function's comment or I
 > I can begin hacking/reading its implementation.
 > 
 > People are breaking a common existing practice without offering a
 > replacement.  Why isn't that "Not cool."?
 > If I'm missing something I'll happily document it in the wiki, augment
 > Makefile's, or whatever.
 > I just want to continue to be able to hack on gdb as easily as I could
 > before people started doing this.

Ok, so here's a first pass at something to alleviate the growing pain.  Bleah.
It's just a prototype, but it seems to have promise in my initial testing.

2014-03-26  Doug Evans  <dje@google.com>

	* Makefile.in (DTAGS): New rule.
	(tags): Add DTAGS dependency.
	* contrib/dtags.el: New file.

diff --git a/gdb/Makefile.in b/gdb/Makefile.in
index 3efedc8..f20512a 100644
--- a/gdb/Makefile.in
+++ b/gdb/Makefile.in
@@ -1346,9 +1346,11 @@ gdb1$(EXEEXT): gdb$(EXEEXT)
 # Put the proper machine-specific files first, so M-. on a machine
 # specific routine gets the one for the correct machine.  (FIXME: those
 # files go in twice; we should be removing them from the main list).
-
-# TAGS depends on all the files that go into it so you can rebuild TAGS
-# with `make TAGS' and not have to say `rm TAGS' first.
+# TAGS,DTAGS depend on all the files that go into them so they can be
+# rebuilt without having to remove them first.
+# Because more and more function comments are being moved to headers,
+# we now create a second tags file, DTAGS, which contains just the
+# headers.  See contrib/dtags.el for example code on how to use it.
 
 GDB_NM_FILE = @GDB_NM_FILE@
 TAGS: $(TAGFILES_NO_SRCDIR) $(TAGFILES_WITH_SRCDIR)
@@ -1361,7 +1363,16 @@ TAGS: $(TAGFILES_NO_SRCDIR) $(TAGFILES_WITH_SRCDIR)
 	done) | sed -e 's/\.o$$/\.c/'` \
 	`find $(srcdir)/config -name '*.h' -print`
 
-tags: TAGS
+DTAGS: $(HFILES_NO_SRCDIR) $(HFILES_WITH_SRCDIR)
+	@echo Making DTAGS
+	etags -o $@ --declarations \
+	    `(for i in $(HFILES_NO_SRCDIR); do \
+		echo $(srcdir)/$$i ; \
+	done ; for i in $(HFILES_WITH_SRCDIR); do \
+		echo $$i ; \
+	done)`
+
+tags: TAGS DTAGS
 
 clean mostlyclean: $(CONFIG_CLEAN)
 	@$(MAKE) $(FLAGS_TO_PASS) DO=clean "DODIRS=$(CLEANDIRS)" subdir_do
diff --git a/gdb/contrib/dtags.el b/gdb/contrib/dtags.el
new file mode 100644
index 0000000..a90783c
--- /dev/null
+++ b/gdb/contrib/dtags.el
@@ -0,0 +1,73 @@
+;; DTAGS support.
+;; Copyright (C) 2014 Free Software Foundation, Inc.
+;;
+;; This program is free software; you can redistribute it and/or modify
+;; it under the terms of the GNU General Public License as published by
+;; the Free Software Foundation; either version 3 of the License, or
+;; (at your option) any later version.
+;;
+;; This program is distributed in the hope that it will be useful,
+;; but WITHOUT ANY WARRANTY; without even the implied warranty of
+;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+;; GNU General Public License for more details.
+;;
+;; You should have received a copy of the GNU General Public License
+;; along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+;; DTAGS is just a variant of TAGS that contains declarations from header
+;; files for documentation purposes.  The "D" in DTAGS is for documentation,
+;; not declaration.  It's needed because more and more function comments
+;; are being moved to headers, making M-. less and less useful.
+;; The goal is to support fast lookup of a function's comment.
+;;
+;; N.B. This is just a prototype cribbed from emacs's etags.el.
+
+(defvar doc-tags-file-name nil
+  "*File name of doc tags table.
+To switch to a new doc tags table, setting this variable is sufficient.
+If you set this variable, do not also set `doc-tags-table-list'.
+Use the `etags' program to make a tags table file.")
+
+(defcustom doc-tags-table-list nil
+  "*List of file names of tags tables to search.
+An element that is a directory means the file \"TAGS\" in that directory.
+To switch to a new list of tags tables, setting this variable is sufficient.
+If you set this variable, do not also set `doc-tags-file-name'.
+Use the `etags' program to make a tags table file."
+  :group 'etags
+  :type '(repeat file))
+
+(defun find-doc-tag (tagname &optional next-p regexp-p)
+  "Find tag (in current tags table) whose name contains TAGNAME.
+Select the buffer containing the tag's definition, and move point there.
+The default for TAGNAME is the expression in the buffer around or before point.
+
+If second arg NEXT-P is t (interactively, with prefix arg), search for
+another tag that matches the last tagname or regexp used.  When there are
+multiple matches for a tag, more exact matches are found first.  If NEXT-P
+is the atom `-' (interactively, with prefix arg that is a negative number
+or just \\[negative-argument]), pop back to the previous tag gone to.
+
+If third arg REGEXP-P is non-nil, treat TAGNAME as a regexp.
+
+A marker representing the point when this command is invoked is pushed
+onto a ring and may be popped back to with \\[pop-tag-mark].
+Contrast this with the ring of marks gone to by the command.
+
+See documentation of variable `tags-file-name'."
+  ;; FIXME: Assumes using tags-file-name, and not tags-table-list.
+  (interactive (find-tag-interactive "Find doc tag: "))
+  (let ((tags-file-name doc-tags-file-name)
+	(tags-table-list doc-tags-table-list))
+    (let* ((buf (find-tag-noselect tagname next-p regexp-p))
+	   (pos (with-current-buffer buf (point))))
+      (setq doc-tags-file-name tags-file-name)
+      (setq doc-tags-table-list tags-table-list)
+      (condition-case nil
+	  (switch-to-buffer buf)
+	(error (pop-to-buffer buf)))
+      (goto-char pos))))
+
+;; TODO: visit-doc-tags-table, anything else?
+
+;;(global-set-key "\M-," 'find-doc-tag)

Re: [RFC] Stop putting function comments in foo.h

[Pedro Alves]

On 03/26/2014 04:45 PM, Doug Evans wrote:
> On Tue, Mar 18, 2014 at 8:59 AM, Doug Evans <dje@google.com> wrote:
>> On Mon, Mar 17, 2014 at 9:07 AM, Pedro Alves <palves@redhat.com> wrote:
>>> IMO, a module's API documentation should be in its header file, as
>>> that's where the module's "public" contract is defined.
>>> Needing to peek at the module's implementation feels wrong to me.
>>> If the function's documentation isn't clear without looking
>>> at the function's body, something is already wrong with
>>> the comment.
>>
>> It use to be that M-. took me to the function definition and its documentation.
>>
>> I'm curious what other emacs+etags users do now.
> 
> fwiw, I'd REALLY like an answer to this.
> 
> M-. worked great before people started moving function comments to headers.
> I can be looking at any function in the source, put the cursor over
> its name, M-. RET, and voila!  I'm reading the function's comment or I
> I can begin hacking/reading its implementation.

I've never actually got used to use M-. myself (always tend to end
up grepping), but I've recently started using cedet (from bzr).

Alex Ott has a good writing on it:

 http://alexott.net/en/writings/emacs-devenv/EmacsCedet.html

E.g., semantic-analyze-proto-impl-toggle toggles between declaration
and implementation.  Or semantic-ia-fast-jump takes you to a variable/function's
declaration.

He has a git tree with handy bits to crib from:
 https://github.com/alexott/emacs-configs/blob/master/rc/emacs-rc-cedet.el

-- 
Pedro Alves