From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 3780 invoked by alias); 26 Mar 2014 16:45:32 -0000 Mailing-List: contact gdb-patches-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sourceware.org Received: (qmail 3770 invoked by uid 89); 26 Mar 2014 16:45:31 -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-ve0-f170.google.com Received: from mail-ve0-f170.google.com (HELO mail-ve0-f170.google.com) (209.85.128.170) by sourceware.org (qpsmtpd/0.93/v0.84-503-g423c35a) with (AES128-SHA encrypted) ESMTPS; Wed, 26 Mar 2014 16:45:30 +0000 Received: by mail-ve0-f170.google.com with SMTP id pa12so2673555veb.15 for ; Wed, 26 Mar 2014 09:45:28 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:mime-version:in-reply-to:references:date :message-id:subject:from:to:cc:content-type; bh=Vy7cqiSEzBaEmyFO6Mz7cTFyU30fGyX9VUdhBLj8gCA=; b=RdSWcbx4SxWIixtQOBHtLhqqMvrozhNzO56ZgMN7H12lSi76xT3AH0pQD2OBHxb1lb HxJD1SVFIWJrWXL9I0YQnOzIRVIxFrTgMwcgFD2AyXvDFTGhiMn6FNIWPxONeg2mxxY4 sSAP+tVKPMzkYh3X/CSe5FpPidjWNcwcmBv4NkcSEdLUQ5O7SyEH2HDuljlrRvgOS9wy NF+Z4Ggui7eAzvsCpgtDKgq8JV9V6cEnS3AB+LB5Etf5c+ZZ+iBlS09Uq9mEvJ1xWR7X Ri6qKOf7VEcEqeaYXZ2enWTBJwLeidj2aqFRyGPlRb7ZEVU3odPrds/RSWjWz6k9u7sX QKHw== X-Gm-Message-State: ALoCoQmlWl9RTLZDSQS2KzpP1UvUrMsp8Q1taxFsjWyHn6QACY2ky+i7VLAEk58g1lMzUa5px9ECwsnP39PrGPIMi1RCRf8qxpkOXbhM/6i0PygHvoNlSlvCgVQQwnFawE3nnLcxfo+52uBtBgUs8q1x1KB/P+LNvoyAh/7jhRHXne/DK+zLxjUSW3YbwlU46qPhdpSAjvgS5YeqDK+1pBovclX3zCTHZA== MIME-Version: 1.0 X-Received: by 10.52.186.39 with SMTP id fh7mr217465vdc.72.1395852328201; Wed, 26 Mar 2014 09:45:28 -0700 (PDT) Received: by 10.52.13.101 with HTTP; Wed, 26 Mar 2014 09:45:27 -0700 (PDT) In-Reply-To: References: <53271DC0.3050405@redhat.com> Date: Wed, 26 Mar 2014 16:45:00 -0000 Message-ID: Subject: Re: [RFC] Stop putting function comments in foo.h From: Doug Evans To: Pedro Alves Cc: gdb-patches Content-Type: text/plain; charset=UTF-8 X-IsSubscribed: yes X-SW-Source: 2014-03/txt/msg00617.txt.bz2 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.