From patchwork Wed Mar 26 19:05:14 2014 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Doug Evans X-Patchwork-Id: 302 Return-Path: X-Original-To: siddhesh@wilcox.dreamhost.com Delivered-To: siddhesh@wilcox.dreamhost.com Received: from homiemail-mx21.g.dreamhost.com (caibbdcaaahb.dreamhost.com [208.113.200.71]) by wilcox.dreamhost.com (Postfix) with ESMTP id 073D636021B for ; Wed, 26 Mar 2014 12:05:35 -0700 (PDT) Received: by homiemail-mx21.g.dreamhost.com (Postfix, from userid 14314964) id B1962C5E69B; Wed, 26 Mar 2014 12:05:35 -0700 (PDT) X-Original-To: gdb@patchwork.siddhesh.in Delivered-To: x14314964@homiemail-mx21.g.dreamhost.com Received: from sourceware.org (server1.sourceware.org [209.132.180.131]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by homiemail-mx21.g.dreamhost.com (Postfix) with ESMTPS id 83021C5E616 for ; Wed, 26 Mar 2014 12:05:35 -0700 (PDT) DomainKey-Signature: a=rsa-sha1; c=nofws; d=sourceware.org; h=list-id :list-unsubscribe:list-subscribe:list-archive:list-post :list-help:sender:from:mime-version:content-type :content-transfer-encoding:message-id:date:to:cc:subject :in-reply-to:references; q=dns; s=default; b=HAbHs2/5nj6P2tbKlOu H6OPenhILpG3xJdVV6h8KER5RRLEqhw4mIbK9BIF38tgxD/TbJxr9Y6R9WCi0aq6 miKMue1LT0A3qxeQQU5HqD3z1tQRc9Jfa9RwZHmfUkvwV+n/5AAqV6l8kVq+iC0D t6fA6nZL1Gua/G0C7H7kUh/s= DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=sourceware.org; h=list-id :list-unsubscribe:list-subscribe:list-archive:list-post :list-help:sender:from:mime-version:content-type :content-transfer-encoding:message-id:date:to:cc:subject :in-reply-to:references; s=default; bh=xBjFVHVwMa4k3ugXkyWfRyuvB Rk=; b=DEMy7Pd/jsLbed0A2D3ey5PZppTswPMumwKFJgQErmIBuLZWkSBTe4eaE gLCJnEyS72Zp5+LxJWiH28eEFE+x24VaM8JVlfWp2nJcimmE0hiWDBDVFBSq6SPL ffpao375MfTnFPKiuw9uN6jKGhNFOU7rUZpPiSAor+xVOoih68= Received: (qmail 31591 invoked by alias); 26 Mar 2014 19:05:32 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Delivered-To: mailing list gdb-patches@sourceware.org Received: (qmail 31570 invoked by uid 89); 26 Mar 2014 19:05:30 -0000 Authentication-Results: sourceware.org; auth=none X-Virus-Found: No X-Spam-SWARE-Status: No, score=-3.1 required=5.0 tests=AWL, BAYES_00, RCVD_IN_DNSWL_LOW, RP_MATCHES_RCVD, SPF_PASS autolearn=ham version=3.3.2 X-HELO: mail-yh0-f73.google.com Received: from mail-yh0-f73.google.com (HELO mail-yh0-f73.google.com) (209.85.213.73) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with (AES128-SHA encrypted) ESMTPS; Wed, 26 Mar 2014 19:05:17 +0000 Received: by mail-yh0-f73.google.com with SMTP id c41so324776yho.2 for ; Wed, 26 Mar 2014 12:05:15 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:from:mime-version:content-type :content-transfer-encoding:message-id:date:to:cc:subject:in-reply-to :references; bh=956joYldFQ4PV2m9blhnkubf4uFBzhKWYyW5WTD/Jn8=; b=Zo3gKxJkR/vVEUTNec1vAP3jqhTozgzN2ONrBdQF9Gnru4RAoKwOb/YJsl1/up/TLR dmF/X84qQJF9U5ELn9vZpt8x4hl+ZX+qmh1plOKg9l9gst8fQBmFJRbmA/zeNuxgDxrH nBWJfOe2h+QjLnZS9gWjQ7Dpdc5POPsACTFsKKfKCwTaNyV5MMJ2B2OKs+9FCTRZxlZ9 j8/XVtvmSqgFFsff7EdgBbR4rCd7oX1JzJv4in4oL/Y5OPYIpIo4pg8B8FRv33UKzZr6 MjT5PUDAwbZkk6s49NbtBlhQhozebNSk+jPqI3m649qx+kORru6qssOtdc3XhSbWUjOV 23Fw== X-Gm-Message-State: ALoCoQlyzSLfk3sl8HB2NVKy0QOyzbwTIPYk4dy2OQBnn91/W56ovsWrpQi5H7feIx76VNOUg4D1HZrDjSVpwti20fRn9mgJSaMGclLvsA8EcVZEoQ/cBi456csBbWf/KOBbSCM4vvEl5k8AqU891/lfkc0PuFBRmmrx/ZhmCHuFURoMFHduGqB6KYfJfuukS4HmUVHuJzI5VOVFxTTA+xrilCXzByB87A== X-Received: by 10.58.41.39 with SMTP id c7mr22380887vel.25.1395860715184; Wed, 26 Mar 2014 12:05:15 -0700 (PDT) Received: from corp2gmr1-1.hot.corp.google.com (corp2gmr1-1.hot.corp.google.com [172.24.189.92]) by gmr-mx.google.com with ESMTPS id g21si3217053yhe.3.2014.03.26.12.05.15 for (version=TLSv1.1 cipher=ECDHE-RSA-AES128-SHA bits=128/128); Wed, 26 Mar 2014 12:05:15 -0700 (PDT) Received: from ruffy.mtv.corp.google.com (ruffy.mtv.corp.google.com [172.17.128.44]) by corp2gmr1-1.hot.corp.google.com (Postfix) with ESMTP id 9FB7631C207; Wed, 26 Mar 2014 12:05:14 -0700 (PDT) From: Doug Evans MIME-Version: 1.0 Message-ID: <21299.9450.36720.381593@ruffy.mtv.corp.google.com> Date: Wed, 26 Mar 2014 12:05:14 -0700 To: Pedro Alves cc: gdb-patches Subject: Re: [RFC] Stop putting function comments in foo.h In-Reply-To: References: <53271DC0.3050405@redhat.com> X-IsSubscribed: yes X-DH-Original-To: gdb@patchwork.siddhesh.in Doug Evans writes: > On Tue, Mar 18, 2014 at 8:59 AM, Doug Evans wrote: > > On Mon, Mar 17, 2014 at 9:07 AM, Pedro Alves 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 * 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 . + +;; 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)