From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 12451 invoked by alias); 11 Dec 2001 19:16:38 -0000 Mailing-List: contact gdb-patches-help@sources.redhat.com; run by ezmlm Precedence: bulk List-Subscribe: List-Archive: List-Post: List-Help: , Sender: gdb-patches-owner@sources.redhat.com Received: (qmail 12404 invoked from network); 11 Dec 2001 19:16:33 -0000 Received: from unknown (HELO mail-out1.apple.com) (17.254.0.52) by sources.redhat.com with SMTP; 11 Dec 2001 19:16:33 -0000 Received: from mailgate1.apple.com (A17-128-100-225.apple.com [17.128.100.225]) by mail-out1.apple.com (8.11.3/8.11.3) with ESMTP id fBBJGWu03893 for ; Tue, 11 Dec 2001 11:16:32 -0800 (PST) Received: from scv1.apple.com (scv1.apple.com) by mailgate1.apple.com (Content Technologies SMTPRS 4.2.1) with ESMTP id ; Tue, 11 Dec 2001 11:16:12 -0800 Received: from apple.com (spinlock.apple.com [17.202.41.123]) by scv1.apple.com (8.11.3/8.11.3) with ESMTP id fBBJGRk04716; Tue, 11 Dec 2001 11:16:27 -0800 (PST) Message-ID: <3C165B8A.51ABC0A2@apple.com> Date: Tue, 11 Dec 2001 11:16:00 -0000 From: Stan Shebs X-Mailer: Mozilla 4.77C-CCK-MCD {C-UDP; EBM-APPLE} (Macintosh; U; PPC) X-Accept-Language: en MIME-Version: 1.0 To: Jim Blandy CC: Eli Zaretskii , fnf@redhat.com, gdb-patches@sources.redhat.com Subject: Re: RFA: "maint print type" should print all the flag bits References: Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit X-SW-Source: 2001-12/txt/msg00309.txt.bz2 Jim Blandy wrote: > > Eli Zaretskii writes: > > > They're only meant for use by GDB developers. > > > > How do you expect the GDB developers to discover their existence if > > they aren't documented? Even if they do discover their existence, how > > would a developer who never used a particular command know what it > > does? The built-in doc strings are terse and don't explain much. For > > example, suppose i use "maint print type" and see it print > > TYPE_FLAG_TARGET_STUB--how do I figure out what that means? (If you > > think that GDB's sources explain that clearly, think again ;-) > > > > I think every command should be documented in the manual. > > Well, you're right, of course. There's no good reason *not* to > document them, other than laziness. I'll mention again a script that I had Jason write one time (that's probably lost to posterity), which was to collect all the commands in the sources, and all the commands documented in the manual, and diff the two. Very handy, because it shows commands that are not documented, and encourages both manual and source to be written in a fashion that makes it easy for the script to find them. (And yes, the followup suggestion will be to generate both source and doc from a single file, but that's a big project. The comparison script would only take an hour or two to get to the point of bein useful.) On the location of maint command docs, I don't think it matters much whether it is in appendix or regular chapter. Readers will be smart enough to realize that they don't need to use the commands unless a GDB maintainer asks them to run one. Stan