From: Takashi Iwai Subject: Re: a newbie overwhelmed with this API Date: Mon, 06 Aug 2007 14:11:20 +0200 Message-ID: References: <46B46800.6020509@yahoo.com.au> Mime-Version: 1.0 (generated by SEMI 1.14.6 - "Maruoka") Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Return-path: Received: from mx1.suse.de (ns1.suse.de [195.135.220.2]) by alsa0.perex.cz (Postfix) with ESMTP id E66E6103827 for ; Mon, 6 Aug 2007 14:11:20 +0200 (CEST) In-Reply-To: <46B46800.6020509@yahoo.com.au> List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Sender: alsa-devel-bounces@alsa-project.org Errors-To: alsa-devel-bounces@alsa-project.org To: Adam Seychell Cc: alsa-devel@alsa-project.org List-Id: alsa-devel@alsa-project.org At Sat, 04 Aug 2007 21:50:24 +1000, Adam Seychell wrote: > > I'm writing simple audio application and I have successfully used the > DirectSound API under Windows. Now I'm looking at porting to Linux using > ALSA. I have tried reading the online ALSA API documentation, but it > seems too early in development and insufficient compared what one can > learn reading Microsoft's DirectX SDK documentation. Excuse my ignorance > for a minute, but the API seems quite large compared to DirectSound and > so I'm wondering if there is good reason why so many functions exists ? > Was there an early design decision not to write ALSA in C++ ? > > I would like to help out with documentation but of course I thats > impossible for someone who is a complete novice to the ALSA project. I > know that writing good documentation takes a lot of hard work, > especially for software developers who spend enough time on coding. Its > an unfortunate paradox among all open source projects. Software > developers who posses the knowledge can't readily communicate it to > potential volunteer documentation writers in an open source environment. Yeah, the documentation has always been a problem. What I'd like to propose is: - concentrate only on basic functions, gather up these functions in a page for "basic operations", instead of spreading all over. - drop the rare used functions, from documentation and mark it deprecated eventually. 90% of existing functions could be in this category. Then API references would be much smaller and readable, at least. The additional more verbose description can be added later on. Takashi