From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Eli Zaretskii Newsgroups: gmane.emacs.devel Subject: Re: Tree-sitter documentation Date: Mon, 07 Nov 2022 14:11:55 +0200 Message-ID: <83a653ynec.fsf@gnu.org> References: <48A65188-BBC6-442F-A552-5FEA1416F936@gmail.com> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="37020"; mail-complaints-to="usenet@ciao.gmane.io" Cc: emacs-devel@gnu.org To: Yuan Fu Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Mon Nov 07 13:12:44 2022 Return-path: Envelope-to: ged-emacs-devel@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1os0zb-0009PT-Bz for ged-emacs-devel@m.gmane-mx.org; Mon, 07 Nov 2022 13:12:43 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1os0zD-0003yK-8K; Mon, 07 Nov 2022 07:12:19 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1os0zB-0003xm-IY for emacs-devel@gnu.org; Mon, 07 Nov 2022 07:12:17 -0500 Original-Received: from fencepost.gnu.org ([2001:470:142:3::e]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1os0zB-0001DE-AJ; Mon, 07 Nov 2022 07:12:17 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=gnu.org; s=fencepost-gnu-org; h=MIME-version:References:Subject:In-Reply-To:To:From: Date; bh=z7maxBDKxRwu59kh5ORlPIWmgEppFYbOnZgC54ABpiI=; b=hoB9aMm0tGXHVQfjUEF4 LlyHIUWh5bB5p6nB3tagcexKnWnQgu06zWKd65eBtsCvRaOj2AWnnTD/WAzPOSUbkMq45TtE7cBHU VmIqQi0t60BKmN66a6LrbUWIV8y8GD8GK+JOEhvTy5lM9GgDggSFUwB2QbfWWK7z1YB+gMmd1340h WUN537WblOdc/Oxn/kaouORloBhiiCQbBFJImTPOFQCgUF4ZX7AD4oRMZIfolOV50EzY6NZ2/W8dw qtFmXp28lE+UPAB6yj3P+kFl7pOo0Dw1e5BHNpxWy/dquByEAxYKBcXGaQ88JihODH5f1lYvCyELb DQgfHarBB/oM4Q==; Original-Received: from [87.69.77.57] (helo=home-c4e4a596f7) by fencepost.gnu.org with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1os0z4-0004Yx-TM; Mon, 07 Nov 2022 07:12:16 -0500 In-Reply-To: <48A65188-BBC6-442F-A552-5FEA1416F936@gmail.com> (message from Yuan Fu on Mon, 7 Nov 2022 02:13:20 -0800) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.devel:299292 Archived-At: > From: Yuan Fu > Date: Mon, 7 Nov 2022 02:13:20 -0800 > > > This function takes a series of @var{query-spec}s, which are triplets > > @w{@code{@var{:keyword} @var{value} @dots{} @var{query}}}. Each > > @var{query} is a tree-sitter query in either the string, s-expression > > or compiled form. > > > Is is ok to use “triplets” here? Because there can be more than one pair of :keyword and values before a query, eg, > > :keyword value > :keyword value > query In that case, "triplets" is definitely incorrect, but I had no way of understanding that this is possible. It should be possible top describe this kind of argument list, but does it really have to be so complicated? These are not internal functions, so Lisp programmers will have to battle with this signature all the time. Can we make the function's signature easier to document, understand, and use? For example, what about accepting an alist as the argument, where each alist element specifies a query and its keyword/value pairs that customize the query?