[bug#53765] [PATCH 13/17] gnu: Add clojure-com-cognitect-aws-api.

[Maxime Devos]

Reily Siegel schreef op do 03-02-2022 om 19:26 [-0500]:
> +    (description "@code{aws-api} is an idiomatic, data-oriented Clojure
> +library for invoking AWS APIs.
> 
What's an ‘AWS API’?  How do I now if I have one?  Some context is
required here.

>   While the library offers some helper and
> +documentation functions you'll use at development time, the only functions 
> you
> +ever need at runtime are @code{client}, which creates a client for a given
> +service and @code{invoke}, which invokes an operation on the
> +service.
> 

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:

‘[...], try to be factual, mentioning use cases and features.’

‘Keep in mind that the synopsis must be meaningful for a very wide
audience.  For example, “Manipulate alignments in the SAM format” 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 “Manipulate nucleotide sequence alignments”, which
hopefully gives the user a better idea of whether this is what they are
looking for.’

Greetings,
Maxime.

signature.asc
Description: This is a digitally signed message part