GNU bug report logs -
#53765
[PATCH 00/17] Remove limitations on clojure-tools
Previous Next
Full log
View this message in rfc822 format
[Message part 1 (text/plain, inline)]
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 (application/pgp-signature, inline)]
This bug report was last modified 3 years and 58 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.