From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Evgeni Kolev Newsgroups: gmane.emacs.bugs Subject: bug#60805: [PATCH] Extend go-ts-mode with command to add docstring to function Date: Wed, 18 Jan 2023 08:26:39 +0200 Message-ID: References: <83ilh98sln.fsf@gnu.org> <87358dz6hy.fsf@thornhill.no> <83tu0t718s.fsf@gnu.org> <87sfgdtga2.fsf@thornhill.no> Mime-Version: 1.0 Content-Type: text/plain; charset="UTF-8" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="4660"; mail-complaints-to="usenet@ciao.gmane.io" Cc: dev@rjt.dev, Eli Zaretskii , 60805@debbugs.gnu.org To: Theodor Thornhill Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Wed Jan 18 07:28:33 2023 Return-path: Envelope-to: geb-bug-gnu-emacs@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 1pI1w0-0000zg-I5 for geb-bug-gnu-emacs@m.gmane-mx.org; Wed, 18 Jan 2023 07:28:32 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1pI1vd-0005vB-2m; Wed, 18 Jan 2023 01:28:09 -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 1pI1vZ-0005uv-FF for bug-gnu-emacs@gnu.org; Wed, 18 Jan 2023 01:28:05 -0500 Original-Received: from debbugs.gnu.org ([209.51.188.43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1pI1vW-0006U8-0b for bug-gnu-emacs@gnu.org; Wed, 18 Jan 2023 01:28:05 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1pI1vV-0006po-Sd for bug-gnu-emacs@gnu.org; Wed, 18 Jan 2023 01:28:01 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Evgeni Kolev Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Wed, 18 Jan 2023 06:28:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 60805 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: patch Original-Received: via spool by 60805-submit@debbugs.gnu.org id=B60805.167402323326211 (code B ref 60805); Wed, 18 Jan 2023 06:28:01 +0000 Original-Received: (at 60805) by debbugs.gnu.org; 18 Jan 2023 06:27:13 +0000 Original-Received: from localhost ([127.0.0.1]:38918 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pI1ui-0006oh-Mh for submit@debbugs.gnu.org; Wed, 18 Jan 2023 01:27:13 -0500 Original-Received: from mail-qv1-f41.google.com ([209.85.219.41]:38821) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1pI1ug-0006oQ-Vg for 60805@debbugs.gnu.org; Wed, 18 Jan 2023 01:27:11 -0500 Original-Received: by mail-qv1-f41.google.com with SMTP id k12so2349508qvj.5 for <60805@debbugs.gnu.org>; Tue, 17 Jan 2023 22:27:10 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20210112; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:from:to:cc:subject:date:message-id:reply-to; bh=LnHC0x109MAA1gdVpgCkO+Y/JgctZFwth/iqfcWVsVs=; b=Ds+n+jOcKu2vQgIvRdUxXrTv6/DdiMRrGDcIPRX2sA9ZUzRjka5nSZS4L45TLiFFCT i2z98C1ypEbyP1kTbbh70Nvm1IO6W9C0Swt08+Xu5QQ+1zp7CPWah0FR421SVe4pWU3V iyAlO5xmbbxD/R1RIi1d6/RfMs4eOdk97wmCPsCcVvzziQ6NUn/BSOw1UEqioA19NE0r 4CfGbCLx7IOkm3xpSZbQMJXElYLQvNRwQh9cOAOPAR6pn8Inrcc6roIEegy8QtWajfLS SFofP2ICZ4hq1FYhXjseikuGDiEVKgepQGXfgE775iP8MU8x3Kl5qEqM63KBh/Q6IJmV LE7g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20210112; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=LnHC0x109MAA1gdVpgCkO+Y/JgctZFwth/iqfcWVsVs=; b=YA8L8o/OJyCov5t0wcwg6yIYK6CUdKcpneQTq63Bk4aiddjjEr7dtTZtSauqACipTk rt8ug75w4omxIWy/eKsl5+C1WeyjxSTbZiADLFLEUzvDlI5q8rJWYfQ4OFmMRCIktdbY ZiS/crBG9yd+QDtmogp6tIfdQmSOTSfMpcHw5f6TYGKuZ8NiQLqoJiJT9myZJ4zwC9ER 83zv514ZofRz2/G2/b54agKrzfGLBa4B2DrUoGys93iq+7Fm613YcdAcVasiVBX8q0lQ nunXgBxST/W+Z5hIqTjQHEaA28gGoRbScTJczF9TiD2D1Tb6wynf46EPIJL+ahnWSz6V BmIg== X-Gm-Message-State: AFqh2kq6tGvvn+IeWJgsqCa9XqTOcWm7MWZ4eu53C5vhAw0tPaa3Ejsa zqNeU0lnMjM2BceGGFOKfhtvtxnyVcFY/zbwNZc= X-Google-Smtp-Source: AMrXdXtRkA4EL5xBdZ3b2BD0Kjq9VbV3zTQ77/d6b6C4yAGZ+jaAKr8ZSawL2CNDfUsGwLimrADu9KdJeJ+19D5CR0c= X-Received: by 2002:a0c:f8cb:0:b0:531:8b09:7654 with SMTP id h11-20020a0cf8cb000000b005318b097654mr315217qvo.70.1674023225157; Tue, 17 Jan 2023 22:27:05 -0800 (PST) In-Reply-To: <87sfgdtga2.fsf@thornhill.no> X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.bugs:253608 Archived-At: Regarding snippet support - I think it makes sense in general, but for this particular patch, not really. Go's docstrings don't typically follow a strict template, instead they are a human-readable comment which tries to be short but also describe any corner cases - very similar to Emacs' doc strings. I'm pasting below a few Go examples from https://go.dev/doc/comment > Is this really the best Emacs can do to produce such a comment? ... I'm asking whether Emacs could collect more information about the function, and provide a skeleton of a useful doc comment for the user to fill. Emacs could fill in the inputs and outputs as variable names but I don't think this will be very useful because the doc strings don't follow a strict template (as mentioned above). Something like this is an option: ``` // sum accepts a and b and returns an int func sum(a, b int) int { return a + b } ``` The above approach wouldn't work so well on non-functions. > What do other IDEs do for this kind of functionality? I'll do some research, I haven't used other IDEs. > Please observe our convention of leaving 2 spaces between sentences. Sorry, I didn't run checkdoc before posting the patch. Go example docstrings are below. ``` // A Buffer is a variable-sized buffer of bytes with Read and Write methods. // The zero value for Buffer is an empty buffer ready to use. type Buffer struct { ... } ... // Copy copies from src to dst until either EOF is reached // on src or an error occurs. It returns the total number of bytes // written and the first error encountered while copying, if any. // // A successful Copy returns err == nil, not err == EOF. ... func Copy(dst Writer, src Reader) (n int64, err error) { ... } // Exit causes the current program to exit with the given status code. // Conventionally, code zero indicates success, non-zero an error. // The program terminates immediately; deferred functions are not run.... func Exit(code int) { ... } ```