From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on inbox.vuxu.org X-Spam-Level: X-Spam-Status: No, score=-1.0 required=5.0 tests=MAILING_LIST_MULTI, RCVD_IN_DNSWL_NONE autolearn=ham autolearn_force=no version=3.4.2 Received: from primenet.com.au (ns1.primenet.com.au [203.24.36.2]) by inbox.vuxu.org (OpenSMTPD) with ESMTP id 8eb187fa for ; Sun, 1 Dec 2019 21:53:47 +0000 (UTC) Received: (qmail 12301 invoked by alias); 1 Dec 2019 21:53:42 -0000 Mailing-List: contact zsh-workers-help@zsh.org; run by ezmlm Precedence: bulk X-No-Archive: yes List-Id: Zsh Workers List List-Post: List-Help: List-Unsubscribe: X-Seq: 44969 Received: (qmail 8088 invoked by uid 1010); 1 Dec 2019 21:53:42 -0000 X-Qmail-Scanner-Diagnostics: from mail-yb1-f177.google.com by f.primenet.com.au (envelope-from , uid 7791) with qmail-scanner-2.11 (clamdscan: 0.102.0/25649. spamassassin: 3.4.2. Clear:RC:0(209.85.219.177):SA:0(-1.9/5.0):. Processed in 2.048218 secs); 01 Dec 2019 21:53:42 -0000 X-Envelope-From: dana@dana.is X-Qmail-Scanner-Mime-Attachments: | X-Qmail-Scanner-Zip-Files: | Received-SPF: pass (ns1.primenet.com.au: SPF record at _netblocks.google.com designates 209.85.219.177 as permitted sender) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:content-transfer-encoding:mime-version :subject:message-id:date:to; bh=YVLClBXz80VwiHKmkRHtd8mpOpIhJn9Ff+cJz4p6hrg=; b=T++NzJVyYJKWbUhVCVbKUTMu8LiEqPGNIoYehnQncGK69JLHs1jOt56O2H1AsqI/rW WOFvZLBk5tpXW5rw6VEi7HFh1D0h7dedwdZlri4EdJ6J0Rv/L7wq6yTu7bhmeNGqPvzB auzfpSQpSO6QBdvy+EEyvYSXi75uRWPZIrpCKnxbCm+U8BY4SewMm8H7r787SN5VQK4W eglOTVPjo5EidjtNVsCIe09uo8FXSA6fxECsuxB820XrG947Cqmt9scPjLgkX6FYLX9R 5JIGvY8o3lIoi1dRo67LM5JLN5DVG+xMasEjNTX8qE8/PpY26Z0PsQ/9JOh8m9gfZUbD yD0w== X-Gm-Message-State: APjAAAVenIfs7umLtTgjC/RKWaZGkXRT+Bo+Z5j3BpZqKND3hcspVO91 bIF12HDTWeI3vnr9iV/KGp4vK45HZ2ekfA== X-Google-Smtp-Source: APXvYqzquwN6ws3HM2Iz1p6HvE+Yrli2DdPhBEn4ey56ZIsxLW0AfgyF+J+HJc7Y00Qo2vGbsvML0Q== X-Received: by 2002:a25:ca07:: with SMTP id a7mr47022823ybg.340.1575237186881; Sun, 01 Dec 2019 13:53:06 -0800 (PST) From: dana Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Mime-Version: 1.0 (Mac OS X Mail 12.4 \(3445.104.11\)) Subject: [PATCH] Update completion style guide Message-Id: <272735B8-D83B-4FCF-8CBF-77922D2FB5AD@dana.is> Date: Sun, 1 Dec 2019 15:53:05 -0600 To: Zsh hackers list X-Mailer: Apple Mail (2.3445.104.11) Some additions to the completion style guide based on the comments here: https://github.com/zsh-users/zsh/pull/36 I haven't seen anyone else complain about the superfluous descriptions, so maybe i'm editorialising a bit, but hopefully it's reasonable? dana diff --git a/Etc/completion-style-guide b/Etc/completion-style-guide index af7c46bfd..53d522764 100644 --- a/Etc/completion-style-guide +++ b/Etc/completion-style-guide @@ -69,12 +69,35 @@ for example, do not use: '--timeout[specify connection timeout in milliseconds]:timeout' but use: '--timeout[specify connection timeout]:timeout (ms)' - +To indicate a default value, use square brackets: + '--timeout[specify connection timeout]:timeout (ms) [5000]' +These two conventions can be used together or individually as appropriate. + Group descriptions should be singular because only one thing is being completed even though many may be listed. This applies even where you complete a list of the things. Tags, functions for completing types of things (such as _files), and states should have plural names. +Group descriptions can be omitted where they are handled by a helper/type +function. For example, the `file' description in the following line is +unnecessary, as `_files' provides it by default: + '--import=[import specified file]:file:_files' +In this case, the following syntax can be used instead: + '--import=[import specified file]: :_files' +Of course, it may make sense to add an explicit description which is +more specific than the default: + '--config=[use specified config file]:config file:_files' + +Similarly, group descriptions can and should be omitted where a `->state' +is involved, as the description in the argument spec is always ignored +in these cases. For example, instead of: + '--config=[use specified config file]:config file:->config-files' +use: + '--config=[use specified config file]: :->config-files' +Setting an explicit description here constitutes (a small amount of) +unnecessary noise, and may be misleading to other developers who update +the function. + In a function, allow any descriptions passed as an argument to override the default you define. For example: _wanted directories expl directory _files -/ "$@" -