From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 30654 invoked by alias); 29 Jun 2008 05:33:50 -0000 Received: (qmail 30640 invoked by uid 22791); 29 Jun 2008 05:33:48 -0000 X-Spam-Check-By: sourceware.org Received: from mail.codesourcery.com (HELO mail.codesourcery.com) (65.74.133.4) by sourceware.org (qpsmtpd/0.31) with ESMTP; Sun, 29 Jun 2008 05:33:31 +0000 Received: (qmail 15296 invoked from network); 29 Jun 2008 05:33:29 -0000 Received: from unknown (HELO wind.local) (vladimir@127.0.0.2) by mail.codesourcery.com with ESMTPA; 29 Jun 2008 05:33:29 -0000 From: Vladimir Prus To: Stan Shebs Subject: Re: [MI non-stop 0/11] Series overview Date: Sun, 29 Jun 2008 05:38:00 -0000 User-Agent: KMail/1.9.9 Cc: gdb-patches@sources.redhat.com References: <200806282033.28441.vladimir@codesourcery.com> <48667869.2090808@earthlink.net> In-Reply-To: <48667869.2090808@earthlink.net> MIME-Version: 1.0 Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: 7bit Content-Disposition: inline Message-Id: <200806290933.30066.vladimir@codesourcery.com> 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 X-SW-Source: 2008-06/txt/msg00570.txt.bz2 On Saturday 28 June 2008 21:44:09 Stan Shebs wrote: > Vladimir Prus wrote: > > Eli Zaretskii wrote: > > > > > >>> From: Vladimir Prus > >>> Date: Sat, 28 Jun 2008 20:33:27 +0400 > >>> > >>> > >>> All patches are ready to be committed, except the patch for enabling non-stop > >>> with a single command -- that one needs discussion. > >>> > >> What about documenting the new features? > >> > > > > Why do you think the MI non-stop spec and the thread behaviour spec were written? > > As usual, and even more than usual due to huge amount of text, I'm not going to > > mess with texinfo until I'm sure nobody has big objections about the behaviour. > > > I'm with Eli on this actually. I can sympathize with the desire not to > waste time writing about code that won't go in, but if as you say, the > patches are ready to be committed, and the basic design has already been > approved, then it seems pretty likely that any documentation text will > receive at most minor changes. The specs are good to have too, but > they're not really a replacement for user documentation; in fact they > should be fodder for the internals manual. Well, since we're talking about MI -- which is fairly formal protocol itself, spec is very close to what will come in documentation. > A beneficial side effect of preparing doc text with the code is that it > helps reviewers relate the code changes to intended observable behavior, > whereas the spec might or might not be out of date, things having > changed due to implementation issues or feedback on related work. By my book, spec that's not up-to-date is not a spec :-) - Volodya