From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 19280 invoked by alias); 24 Dec 2011 07:45:35 -0000 Received: (qmail 19246 invoked by uid 22791); 24 Dec 2011 07:45:32 -0000 X-SWARE-Spam-Status: No, hits=-0.8 required=5.0 tests=AWL,BAYES_00,SPF_SOFTFAIL X-Spam-Check-By: sourceware.org Received: from mtaout20.012.net.il (HELO mtaout20.012.net.il) (80.179.55.166) by sourceware.org (qpsmtpd/0.43rc1) with ESMTP; Sat, 24 Dec 2011 07:45:18 +0000 Received: from conversion-daemon.a-mtaout20.012.net.il by a-mtaout20.012.net.il (HyperSendmail v2007.08) id <0LWP00L006SAHN00@a-mtaout20.012.net.il> for gdb-patches@sourceware.org; Sat, 24 Dec 2011 09:45:17 +0200 (IST) Received: from HOME-C4E4A596F7 ([77.127.84.173]) by a-mtaout20.012.net.il (HyperSendmail v2007.08) with ESMTPA id <0LWP00LQA6VG9C30@a-mtaout20.012.net.il>; Sat, 24 Dec 2011 09:45:16 +0200 (IST) Date: Sat, 24 Dec 2011 13:21:00 -0000 From: Eli Zaretskii Subject: Re: FYI: minsyms documentation In-reply-to: <4EF54B6D.907@codesourcery.com> To: Yao Qi Cc: gdb-patches@sourceware.org Reply-to: Eli Zaretskii Message-id: <83obuyxvjl.fsf@gnu.org> References: <4EF38DAD.3040106@earthlink.net> <8362h8z60x.fsf@gnu.org> <4EF39E85.3050207@earthlink.net> <4EF54B6D.907@codesourcery.com> X-IsSubscribed: yes 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: 2011-12/txt/msg00818.txt.bz2 > Date: Sat, 24 Dec 2011 11:47:57 +0800 > From: Yao Qi > > newbies are learning by manual reading at the beginning Then they will learn a lot of incorrect things at the beginning. > In JDK, all the documentation to a class and its methods are written in > source file, and only one small text file is for package description. > In package description, the overview is given and relationship of these > classes is described. Most of the doc in details are still in comment > of source file. I don't think we can copy this approach here, but we > can do something similar here. Put detailed doc in gdbint.texinfo to > relevant source files, and only leave overview and high-level doc in it. > In this way, we don't have to pay much effort to keep gdbint.texinfo > synchronized with source, and gdbint.texinfo is still quite useful. Take a look at libiberty and at bfd: they use something very similar. We could do the same with gdbint.texinfo (I think I proposed that as well some time ago, but no one was for it).