From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp10.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms0.migadu.com with LMTPS id OMWHL4ap/2HpcgAAgWs5BA (envelope-from ) for ; Sun, 06 Feb 2022 11:57:10 +0100 Received: from aspmx1.migadu.com ([2001:41d0:2:4a6f::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp10.migadu.com with LMTPS id AEs8KIap/2EgwQAAG6o9tA (envelope-from ) for ; Sun, 06 Feb 2022 11:57:10 +0100 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id 59C961151E for ; Sun, 6 Feb 2022 11:57:10 +0100 (CET) Received: from localhost ([::1]:40710 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1nGfED-0007gV-1y for larch@yhetil.org; Sun, 06 Feb 2022 05:57:09 -0500 Received: from eggs.gnu.org ([209.51.188.92]:54180) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1nGf45-0004Ad-7H for guix-patches@gnu.org; Sun, 06 Feb 2022 05:46:42 -0500 Received: from debbugs.gnu.org ([209.51.188.43]:42680) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1nGf3S-0004RE-Dh for guix-patches@gnu.org; Sun, 06 Feb 2022 05:46:38 -0500 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1nGf3S-00071U-90 for guix-patches@gnu.org; Sun, 06 Feb 2022 05:46:02 -0500 X-Loop: help-debbugs@gnu.org Subject: [bug#53765] [PATCH 13/17] gnu: Add clojure-com-cognitect-aws-api. Resent-From: Maxime Devos Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Sun, 06 Feb 2022 10:46:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 53765 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: Reily Siegel , 53765@debbugs.gnu.org Received: via spool by 53765-submit@debbugs.gnu.org id=B53765.164414431826936 (code B ref 53765); Sun, 06 Feb 2022 10:46:02 +0000 Received: (at 53765) by debbugs.gnu.org; 6 Feb 2022 10:45:18 +0000 Received: from localhost ([127.0.0.1]:36577 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nGf2k-00070O-7l for submit@debbugs.gnu.org; Sun, 06 Feb 2022 05:45:18 -0500 Received: from andre.telenet-ops.be ([195.130.132.53]:45230) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1nGf2i-00070G-Ng for 53765@debbugs.gnu.org; Sun, 06 Feb 2022 05:45:17 -0500 Received: from [172.20.10.5] ([188.188.251.13]) by andre.telenet-ops.be with bizsmtp id rmlE2600b0J677g01mlF73; Sun, 06 Feb 2022 11:45:15 +0100 Message-ID: From: Maxime Devos Date: Sun, 06 Feb 2022 11:45:14 +0100 In-Reply-To: <87ee4j32av.fsf@reilysiegel.com> References: <87y22r32hi.fsf@reilysiegel.com> <87ee4j32av.fsf@reilysiegel.com> Content-Type: multipart/signed; micalg="pgp-sha512"; protocol="application/pgp-signature"; boundary="=-6yv0//AhYo5MY9rRM2Q0" User-Agent: Evolution 3.38.3-1 MIME-Version: 1.0 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=telenet.be; s=r22; t=1644144315; bh=NedNleb6oqksmEXo1ROyC8dNnsl3KHiIGDx/PWF7ABA=; h=Subject:From:To:Date:In-Reply-To:References; b=BZbkFaHW+r3z0H4wwP4f/S/P9eaBC2gwqy9FGiu4djwsWOJ+4nMPPsL6FZ7DvsCkg I6SIy/SZNANGMWN+eZ3da/7t3o20Z/SXfvr6c5OFYxHSZa7hPYYtsz/ungqER1e1l7 q5PVccRatbBVDTpu9sW1rbcBlD2S6QISfJ76CLjPaJ2axC2Th2h6qyaYzKLd7WnitE geIq1wmqJRjqb50H/L95TAw87ZMqqdcM6P7N8+rmn7Jy5dKHRn9RRh8X8/iTeHHMjt kMDe8U4dvjHDjRvxg7+j+kdXAxyknyGqJNgonVche7E+FoQEEctsde9PtE69oBQymR j2UTzVRpPlgTQ== X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: guix-patches@gnu.org List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+larch=yhetil.org@gnu.org Sender: "Guix-patches" X-Migadu-Flow: FLOW_IN X-Migadu-Country: US ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1644145030; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:mime-version:mime-version: content-type:content-type:resent-cc:resent-from:resent-sender: resent-message-id:in-reply-to:in-reply-to:references:references: list-id:list-help:list-unsubscribe:list-subscribe:list-post: dkim-signature; bh=NedNleb6oqksmEXo1ROyC8dNnsl3KHiIGDx/PWF7ABA=; b=rEyNYkboRYTYG2wU8kb6xvNcJd7tYO6euWEY06Cjs0wWjLsK/xet/f+jqCqG3mJhry3CsF F7iZluSaJHymkGwM+OhC8tKAYuf04gB2diGUuyL5ydPkjZIxpu1Jija59WHJ8a1hIz8d3b eeujp1mURtsiWu8MgIgxPZNjjxkssXojVhnp8Pu/DtNwLQh++fU8aBaMffB3A5GayAIuQc 8UYdZ+xkvZqMw/i7kNSg9QNJVpEwdIgAhFvlVodcfBdpF5ji776T4BOcs9EpPs1JgdYYa1 lUJOLYN9KX5HPdl5FcbIN/PUTV3uBfPbAsPU2+cPWqDJkNBXw9mJuwOx9Cp39Q== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1644145030; a=rsa-sha256; cv=none; b=ZhF9kBEMiyssvlfGSTKe6+MjXhSR7fMrEOViW6USQqJwinw/bTdBZ9PHj6WSMjX0L7viyk r2oxLq6BzeshTjOcEXI9Nuu4OaeR0WOhGSMHUHIUyQHf3EPqW0vaptC3vjuh72Ha7yc2+y qzurDQcJ/AEJVEYzgPMfuTupMkJbZiFhDi15S9Pqb4sAjsj1rj1TrvTbPfWG3a9Y86KllW Ne3J5sb0pZqHVg+/g5c4vVwdw7+bJtDisRqBn0MRdd6kqNyGJiaheSK7b0Sl09fqRuhoJD +PYu/rrrJ7W+v2pMZ7jGi7bnD4gRRy9yG7lrmvsNZLZJiSbd/4rdArGALrNQzQ== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=telenet.be header.s=r22 header.b=BZbkFaHW; dmarc=fail reason="SPF not aligned (relaxed)" header.from=telenet.be (policy=none); spf=pass (aspmx1.migadu.com: domain of "guix-patches-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-patches-bounces+larch=yhetil.org@gnu.org" X-Migadu-Spam-Score: -4.23 Authentication-Results: aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=telenet.be header.s=r22 header.b=BZbkFaHW; dmarc=fail reason="SPF not aligned (relaxed)" header.from=telenet.be (policy=none); spf=pass (aspmx1.migadu.com: domain of "guix-patches-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="guix-patches-bounces+larch=yhetil.org@gnu.org" X-Migadu-Queue-Id: 59C961151E X-Spam-Score: -4.23 X-Migadu-Scanner: scn1.migadu.com X-TUID: ifuX2M2ucZBZ --=-6yv0//AhYo5MY9rRM2Q0 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable Reily Siegel schreef op do 03-02-2022 om 19:26 [-0500]: > +=C2=A0=C2=A0=C2=A0 (description "@code{aws-api} is an idiomatic, data-or= iented Clojure > +library for invoking AWS APIs. >=20 What's an =E2=80=98AWS API=E2=80=99? How do I now if I have one? Some con= text is required here. > =C2=A0 While the library offers some helper and > +documentation functions you'll use at development time, the only functio= ns you > +ever need at runtime are @code{client}, which creates a client for a giv= en > +service and @code{invoke}, which invokes an operation on the > +service. >=20 How can this description now I will never need these helper functions? If they are unneeded, why are they included at all? > @code{invoke} takes a map and returns a map, and works the same way > +for every operation on every service.") Anyway, descriptions aren't the place to describe the API, that's for the documentation of clojure-com-cognitect-aws-api. Instead, keep in mind: =E2=80=98[...], try to be factual, mentioning use cases and features.=E2=80= =99 =E2=80=98Keep in mind that the synopsis must be meaningful for a very wide audience. For example, =E2=80=9CManipulate alignments in the SAM format=E2= =80=9D might make sense for a seasoned bioinformatics researcher, but might be fairly unhelpful or even misleading to a non-specialized audience. It is a good idea to come up with a synopsis that gives an idea of the application domain of the package. In this example, this might give something like =E2=80=9CManipulate nucleotide sequence alignments=E2=80=9D,= which hopefully gives the user a better idea of whether this is what they are looking for.=E2=80=99 Greetings, Maxime. --=-6yv0//AhYo5MY9rRM2Q0 Content-Type: application/pgp-signature; name="signature.asc" Content-Description: This is a digitally signed message part Content-Transfer-Encoding: 7bit -----BEGIN PGP SIGNATURE----- iI0EABYKADUWIQTB8z7iDFKP233XAR9J4+4iGRcl7gUCYf+muhccbWF4aW1lZGV2 b3NAdGVsZW5ldC5iZQAKCRBJ4+4iGRcl7uTnAQCDIx/1TWiQgPCXCy5UOL6E9bC2 C+Jz4p/+v6/wUO0NtQD9F8v7fMtSYa8heJL8Ys/PBOt0IIUoAHjynYWh+LIFSgg= =/ggx -----END PGP SIGNATURE----- --=-6yv0//AhYo5MY9rRM2Q0--