From 51fa54f7a93e858af4dc0a389cfd23f49008869a Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Carlos=20Vigil-V=C3=A1squez?= <carlos.vigil.v@gmail.com>
Date: Tue, 15 Sep 2026 19:09:26 +0200
Subject: [PATCH 1/2] docs: validate public API examples

---
 .github/workflows/CI.yml        |  9 ++++---
 docs/make.jl                    |  3 ---
 docs/src/man/examples.md        | 46 ++++++++++++---------------------
 docs/src/man/getting-started.md | 15 +++++++----
 docs/src/man/usecases/case1.md  | 46 +++++++++++++++++++--------------
 docs/src/man/usecases/case2.md  | 13 ++++++++--
 docs/src/man/usecases/case3.md  | 12 +++++++--
 docs/src/man/usecases/case4.md  | 14 ++++++++--
 src/Conv.jl                     | 28 +++++++++++++-------
 src/Ddi.jl                      | 19 +++++++-------
 src/Find.jl                     | 13 +++++-----
 src/Get.jl                      | 44 ++++++++++++++++++++-----------
 src/Info.jl                     | 19 ++++++++------
 src/Link.jl                     | 36 +++++++++++++++++++++-----
 src/List.jl                     | 36 ++++++++++++++++++++------
 src/Requests.jl                 | 13 +++++++---
 16 files changed, 232 insertions(+), 134 deletions(-)

diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml
index fca1ac5..9638907 100644
--- a/.github/workflows/CI.yml
+++ b/.github/workflows/CI.yml
@@ -78,12 +78,13 @@ jobs:
             Pkg.develop(PackageSpec(path=pwd()))
             Pkg.instantiate()'
       - uses: julia-actions/julia-buildpkg@v1
-      - uses: julia-actions/julia-docdeploy@v1
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      - run: |
+      - name: Validate docstrings
+        run: |
           julia --project=docs -e '
             using Documenter: DocMeta, doctest
             using KEGGAPI
             DocMeta.setdocmeta!(KEGGAPI, :DocTestSetup, :(using KEGGAPI); recursive=true)
             doctest(KEGGAPI)'
+      - uses: julia-actions/julia-docdeploy@v1
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
diff --git a/docs/make.jl b/docs/make.jl
index 2bdf923..2593010 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -8,9 +8,6 @@ makedocs(;
     authors = "Nicholas Geoffrion, Maria Victoria Aguilar Pontes, Carlos Vigil-Vásquez",
     repo = "https://github.com/cvigilv/KEGGAPI.jl/blob/{commit}{path}#{line}",
     sitename = "KEGGAPI.jl",
-    # `@example` blocks make live KEGG API calls at build time, so a transient
-    # KEGG outage or endpoint hiccup must not hard-fail the docs deploy.
-    warnonly = [:example_block],
     format = Documenter.HTML(;
         prettyurls = get(ENV, "CI", "false") == "true",
         canonical = "https://cvigilv.github.io/KEGGAPI.jl",
diff --git a/docs/src/man/examples.md b/docs/src/man/examples.md
index 6006c15..206abfd 100644
--- a/docs/src/man/examples.md
+++ b/docs/src/man/examples.md
@@ -1,15 +1,11 @@
 # Examples
 
-## KEGGAPI.conv
+## `kegg_conv`
 
-Examples analogous to [KEGG Conv](https://www.kegg.jp/kegg/rest/keggapi.html#conv)
-
-Querying the API for a simple conversion returns a list with:
-1. The API call
-2. The column headers of the call ( if the result is tabular )
-3. The data
-
-This allows to easily convert to a data frame:
+These examples follow the [KEGG Conv](https://www.kegg.jp/kegg/rest/keggapi.html#conv)
+operation. `kegg_conv` returns a `KeggTupleList` containing the request URL,
+column names, and data. Pass the latter two fields to `DataFrame` to construct a
+data frame:
 
 ```@setup examples
 using KEGGAPI
@@ -17,33 +13,25 @@ using DataFrames
 ```
 
 ```@example examples
-output = KEGGAPI.kegg_conv("eco", "ncbi-geneid"); 
-first(DataFrame(
-  output.data,
-  output.colnames
-), 5)
+output = KEGGAPI.kegg_conv("genes", "ncbi-geneid:948364")
+@assert output isa KEGGAPI.KeggTupleList
+DataFrame(output.data, output.colnames)
 ```
 
 ```@example examples
-output = KEGGAPI.kegg_conv("ncbi-geneid", "eco");
-first(DataFrame(
-  output.data,
-  output.colnames
-), 5)
+output = KEGGAPI.kegg_conv("ncbi-geneid", "eco:b0002")
+@assert output isa KEGGAPI.KeggTupleList
+DataFrame(output.data, output.colnames)
 ```
 
 ```@example examples
-output = KEGGAPI.kegg_conv("ncbi-proteinid", "hsa:10458+ece:Z5100");
-DataFrame(
-  output.data,
-  output.colnames
-)
+output = KEGGAPI.kegg_conv("ncbi-proteinid", ["hsa:10458", "ece:Z5100"])
+@assert output isa KEGGAPI.KeggTupleList
+DataFrame(output.data, output.colnames)
 ```
 
 ```@example examples
-output = KEGGAPI.kegg_conv("genes", "ncbi-geneid:948364");
-DataFrame(
-  output.data,
-  output.colnames
-)
+output = KEGGAPI.kegg_conv("genes", "uniprot:P0A6F9")
+@assert output isa KEGGAPI.KeggTupleList
+DataFrame(output.data, output.colnames)
 ```
diff --git a/docs/src/man/getting-started.md b/docs/src/man/getting-started.md
index bc15222..b1bd223 100644
--- a/docs/src/man/getting-started.md
+++ b/docs/src/man/getting-started.md
@@ -11,18 +11,23 @@ pkg> add KEGGAPI
 
 ## Usage
 
-To use KEGGAPI.jl, simply import the package:
+Load KEGGAPI.jl with `using`:
 
 ```@setup examples
 using KEGGAPI
 ```
 
-And use the interfaces to query the KEGG API. For example, to list all organisms (genomes) in KEGG:
+Then call a wrapper for the KEGG operation you need. For example, list all
+organisms in KEGG:
+
 ```@example examples
-result = KEGGAPI.kegg_list("genome");
+result = KEGGAPI.kegg_list("genome")
+@assert result isa KEGGAPI.KeggTupleList
+nothing # hide
 ```
-This returns a `KeggTupleList` object with the API call, column names and data. The data can
-accessed by indexing into the respective fields of the object:
+
+This returns a `KeggTupleList` containing the request URL, column names, and data.
+Access them through the corresponding fields:
 ```@example examples
 result.url
 ```
diff --git a/docs/src/man/usecases/case1.md b/docs/src/man/usecases/case1.md
index 35d69c8..2456ea2 100644
--- a/docs/src/man/usecases/case1.md
+++ b/docs/src/man/usecases/case1.md
@@ -25,26 +25,26 @@ Only identifiers with a hit in KEGG are returned:
 
 ```@example case1
 conv = KEGGAPI.kegg_conv("genes", "uniprot:A0A072UR65")
+@assert conv isa KEGGAPI.KeggTupleList
 DataFrame(conv.data, conv.colnames)
 ```
 
 Several identifiers from the same database can be converted in one call by
-passing a vector (for example a column read from a CSV file with `CSV.jl`). The
-input is automatically split into chunks of 10 to respect the KEGG rate limit:
+passing a vector. KEGGAPI splits inputs longer than 10 entries into request
+batches:
 
-```julia
-using CSV
-
-df = DataFrame(CSV.File("subset_data.csv"))
-entries = string.("uniprot:", df.Entry)
+```@example case1
+entries = ["uniprot:A0A072UR65", "uniprot:P12345"]
 conv = KEGGAPI.kegg_conv("genes", entries)
-DataFrame(conv.data, conv.colnames)
+@assert conv isa KEGGAPI.KeggTupleList
+conv.url
 ```
 
 The reverse direction (KEGG → outside database) works the same way:
 
 ```@example case1
 conv = KEGGAPI.kegg_conv("ncbi-proteinid", "mtr:25493984")
+@assert conv isa KEGGAPI.KeggTupleList
 DataFrame(conv.data, conv.colnames)
 ```
 
@@ -55,26 +55,24 @@ single entry is returned as a `String` in the `.data` field:
 
 ```@example case1
 gene = KEGGAPI.kegg_get("mtr:25493984")
+@assert gene.url isa String && gene.data isa String
 println(join(first(split(gene.data, "\n"), 8), "\n"))
 ```
 
 ## 3. Download sequences
 
 `kegg_get` can return amino-acid (`:aaseq`) or nucleotide (`:ntseq`) FASTA
-sequences. `.data` holds one FASTA record per requested entry, which you can
-write to a file (e.g. with `FastaIO.jl`):
-
-```julia
-using FastaIO
+sequences. For vector input, `.data` holds one FASTA record per requested entry:
 
+```@example case1
 seqs = KEGGAPI.kegg_get(["mtr:25493984", "shz:shn_30305"], :aaseq)
-FastaWriter("aaseq.fasta") do fw
-    for record in seqs.data
-        write(fw, record)
-    end
-end
+@assert length(seqs.data) == 2 && all(startswith(">"), seqs.data)
+first(split(first(seqs.data), '\n'))
 ```
 
+Write the records with `write("aaseq.fasta", join(seqs.data, '\n'))` or pass
+them to a FASTA package.
+
 ## 4. Orthology, reactions and pathways
 
 [`kegg_link`](@ref) finds cross-references between databases. The orthology (KO)
@@ -82,6 +80,7 @@ group for the gene:
 
 ```@example case1
 ko = KEGGAPI.kegg_link("ko", "mtr:25493984")
+@assert ko isa KEGGAPI.KeggTupleList
 DataFrame(ko.data, ko.colnames)
 ```
 
@@ -89,6 +88,7 @@ Reactions associated with that ortholog:
 
 ```@example case1
 rxns = KEGGAPI.kegg_link("reaction", "K01183")
+@assert rxns isa KEGGAPI.KeggTupleList
 DataFrame(rxns.data, rxns.colnames)
 ```
 
@@ -96,6 +96,7 @@ Pathways the gene participates in:
 
 ```@example case1
 paths = KEGGAPI.kegg_link("pathway", "mtr:25493984")
+@assert paths isa KEGGAPI.KeggTupleList
 DataFrame(paths.data, paths.colnames)
 ```
 
@@ -106,6 +107,7 @@ every member gene across organisms:
 
 ```@example case1
 ko_genes = KEGGAPI.kegg_link("genes", "K01183")
+@assert ko_genes isa KEGGAPI.KeggTupleList
 first(DataFrame(ko_genes.data, ko_genes.colnames), 5)
 ```
 
@@ -118,9 +120,13 @@ a multiple-sequence-alignment input.
 The `:image` option returns the PNG bytes of a pathway map, which you can write
 to disk and open with your favourite image viewer or `Images.jl`:
 
-```julia
+```@example case1
 img = KEGGAPI.kegg_get("map00520", :image)
-open("map00520.png", "w") do io
+@assert img.data isa Vector{UInt8} && !isempty(img.data)
+path = tempname()
+bytes_written = open(path, "w") do io
     write(io, img.data)
 end
+rm(path)
+bytes_written == length(img.data)
 ```
diff --git a/docs/src/man/usecases/case2.md b/docs/src/man/usecases/case2.md
index 772f4b3..c409cbc 100644
--- a/docs/src/man/usecases/case2.md
+++ b/docs/src/man/usecases/case2.md
@@ -15,6 +15,7 @@ using DataFrames
 
 ```@example case2
 rxns = KEGGAPI.kegg_link("reaction", "ec:3.2.1.14")
+@assert rxns isa KEGGAPI.KeggTupleList
 DataFrame(rxns.data, rxns.colnames)
 ```
 
@@ -26,6 +27,7 @@ one flat-file `String` per reaction:
 
 ```@example case2
 info = KEGGAPI.kegg_get(rxns.data[2])
+@assert info.url isa Vector{String} && all(item -> item isa String, info.data)
 println(join(first(split(info.data[1], "\n"), 6), "\n"))
 ```
 
@@ -33,6 +35,7 @@ println(join(first(split(info.data[1], "\n"), 6), "\n"))
 
 ```@example case2
 cpds = KEGGAPI.kegg_link("compound", "rn:R01206")
+@assert cpds isa KEGGAPI.KeggTupleList
 DataFrame(cpds.data, cpds.colnames)
 ```
 
@@ -40,6 +43,7 @@ Retrieve the compound entries the same way as the reactions:
 
 ```@example case2
 cpd_info = KEGGAPI.kegg_get(cpds.data[2])
+@assert cpd_info.url isa Vector{String} && all(item -> item isa String, cpd_info.data)
 println(join(first(split(cpd_info.data[1], "\n"), 6), "\n"))
 ```
 
@@ -48,16 +52,21 @@ println(join(first(split(cpd_info.data[1], "\n"), 6), "\n"))
 The `:image` option returns the PNG bytes for a reaction, which you can save to
 disk:
 
-```julia
+```@example case2
 img = KEGGAPI.kegg_get("rn:R01206", :image)
-open("R01206.png", "w") do io
+@assert img.data isa Vector{UInt8} && !isempty(img.data)
+path = tempname()
+bytes_written = open(path, "w") do io
     write(io, img.data)
 end
+rm(path)
+bytes_written == length(img.data)
 ```
 
 ## 5. Orthology group for a reaction
 
 ```@example case2
 ko = KEGGAPI.kegg_link("ko", "rn:R01206")
+@assert ko isa KEGGAPI.KeggTupleList
 DataFrame(ko.data, ko.colnames)
 ```
diff --git a/docs/src/man/usecases/case3.md b/docs/src/man/usecases/case3.md
index a24fa2c..9339c66 100644
--- a/docs/src/man/usecases/case3.md
+++ b/docs/src/man/usecases/case3.md
@@ -15,6 +15,7 @@ the `compound` database and the compound name:
 
 ```@example case3
 hits = KEGGAPI.kegg_find("compound", "chitin")
+@assert hits isa KEGGAPI.KeggTupleList
 DataFrame(hits.data, hits.colnames)
 ```
 
@@ -25,6 +26,7 @@ the full entry with [`kegg_get`](@ref):
 
 ```@example case3
 cpd = KEGGAPI.kegg_get("cpd:C00461")
+@assert cpd.url isa String && cpd.data isa String
 println(join(first(split(cpd.data, "\n"), 8), "\n"))
 ```
 
@@ -33,11 +35,15 @@ println(join(first(split(cpd.data, "\n"), 8), "\n"))
 The `:image` option returns the PNG bytes of the compound structure, which you
 can save to disk:
 
-```julia
+```@example case3
 img = KEGGAPI.kegg_get("cpd:C00461", :image)
-open("C00461.png", "w") do io
+@assert img.data isa Vector{UInt8} && !isempty(img.data)
+path = tempname()
+bytes_written = open(path, "w") do io
     write(io, img.data)
 end
+rm(path)
+bytes_written == length(img.data)
 ```
 
 ## 4. Reactions linked to the compound
@@ -47,6 +53,7 @@ in:
 
 ```@example case3
 rxns = KEGGAPI.kegg_link("reaction", "cpd:C00461")
+@assert rxns isa KEGGAPI.KeggTupleList
 DataFrame(rxns.data, rxns.colnames)
 ```
 
@@ -57,5 +64,6 @@ Feed the reaction identifiers (the second column of `rxns.data`) back into
 
 ```@example case3
 info = KEGGAPI.kegg_get(rxns.data[2])
+@assert info.url isa Vector{String} && all(item -> item isa String, info.data)
 println(join(first(split(info.data[1], "\n"), 6), "\n"))
 ```
diff --git a/docs/src/man/usecases/case4.md b/docs/src/man/usecases/case4.md
index 17c2529..bf38fa4 100644
--- a/docs/src/man/usecases/case4.md
+++ b/docs/src/man/usecases/case4.md
@@ -16,6 +16,7 @@ only the first few hits:
 
 ```@example case4
 genes = KEGGAPI.kegg_find("genes", "CD19")
+@assert genes isa KEGGAPI.KeggTupleList
 first(DataFrame(genes.data, genes.colnames), 5)
 ```
 
@@ -25,6 +26,7 @@ Retrieve the full entry for the human gene with [`kegg_get`](@ref):
 
 ```@example case4
 gene = KEGGAPI.kegg_get("hsa:930")
+@assert gene.url isa String && gene.data isa String
 println(join(first(split(gene.data, "\n"), 8), "\n"))
 ```
 
@@ -32,6 +34,7 @@ Its orthology (KO) group via [`kegg_link`](@ref):
 
 ```@example case4
 ko = KEGGAPI.kegg_link("ko", "hsa:930")
+@assert ko isa KEGGAPI.KeggTupleList
 DataFrame(ko.data, ko.colnames)
 ```
 
@@ -39,6 +42,7 @@ DataFrame(ko.data, ko.colnames)
 
 ```@example case4
 paths = KEGGAPI.kegg_link("pathway", "hsa:930")
+@assert paths isa KEGGAPI.KeggTupleList
 DataFrame(paths.data, paths.colnames)
 ```
 
@@ -46,6 +50,7 @@ DataFrame(paths.data, paths.colnames)
 
 ```@example case4
 drugs = KEGGAPI.kegg_link("drug", "hsa:930")
+@assert drugs isa KEGGAPI.KeggTupleList
 DataFrame(drugs.data, drugs.colnames)
 ```
 
@@ -54,14 +59,19 @@ second column of `drugs.data`) to `kegg_get`:
 
 ```@example case4
 drug_info = KEGGAPI.kegg_get(drugs.data[2])
+@assert drug_info.url isa Vector{String} && all(item -> item isa String, drug_info.data)
 println(join(first(split(drug_info.data[1], "\n"), 6), "\n"))
 ```
 
 ## 5. Download a pathway map
 
-```julia
+```@example case4
 img = KEGGAPI.kegg_get("hsa04151", :image)
-open("hsa04151.png", "w") do io
+@assert img.data isa Vector{UInt8} && !isempty(img.data)
+path = tempname()
+bytes_written = open(path, "w") do io
     write(io, img.data)
 end
+rm(path)
+bytes_written == length(img.data)
 ```
diff --git a/src/Conv.jl b/src/Conv.jl
index 5c24583..2bc4ab7 100644
--- a/src/Conv.jl
+++ b/src/Conv.jl
@@ -1,5 +1,5 @@
 """
-    kegg_conv(target_db::String, source_db::String)
+    kegg_conv(target_db::String, source_db::String) -> KeggTupleList
 
 Convert KEGG identifiers to/from outside identifiers.
 
@@ -7,13 +7,16 @@ Convert KEGG identifiers to/from outside identifiers.
 - `target_db::String`: Target database
 - `source_db::String`: Source database
 
+# Returns
+- `KeggTupleList`: The requested identifier mappings, with the request URL and
+  column names.
+
 # Examples
-```julia
-using KEGGAPI
+```jldoctest
+julia> result = kegg_conv("genes", "ncbi-geneid:948364");
 
-KEGGAPI.kegg_conv("eco", "ncbi-geneid")
-KEGGAPI.kegg_conv("ncbi-geneid", "eco")
-KEGGAPI.kegg_conv("genes", "ncbi-geneid:948364")
+julia> result isa KEGGAPI.KeggTupleList && !isempty(result.data)
+true
 ```
 
 # Extended help
@@ -37,7 +40,7 @@ end
 
 
 """
-    kegg_conv(target_db::String, dbentries::Vector{String}; request_delay::Real = 0.4, timeout = nothing)
+    kegg_conv(target_db::String, dbentries::Vector{String}; request_delay::Real = 0.4, timeout = nothing) -> KeggTupleList
 
 Convert KEGG identifiers to/from outside identifiers.
 
@@ -60,15 +63,20 @@ For chemical substance identifiers:
 - `timeout::Real`: Deprecated alias for `request_delay`. If both keywords are
   supplied, their values must be equal.
 
+# Returns
+- `KeggTupleList`: The requested identifier mappings, request URLs, and column
+  names.
+
 # Throws
 - `ArgumentError`: If a delay is negative or non-finite, or if `request_delay`
   and `timeout` conflict.
 
 # Examples
-```julia
-using KEGGAPI
+```jldoctest
+julia> result = kegg_conv("ncbi-proteinid", ["hsa:10458", "ece:Z5100"]);
 
-KEGGAPI.kegg_conv("ncbi-proteinid", ["hsa:10458", "ece:Z5100"])
+julia> result isa KEGGAPI.KeggTupleList && result.url isa Vector{String} && !isempty(result.data)
+true
 ```
 """
 function kegg_conv(
diff --git a/src/Ddi.jl b/src/Ddi.jl
index 9181e03..a79ed4d 100644
--- a/src/Ddi.jl
+++ b/src/Ddi.jl
@@ -1,6 +1,6 @@
 """
-    kegg_ddi(dbentry::String)
-    kegg_ddi(dbentries::Vector{String})
+    kegg_ddi(dbentry::String) -> KeggTupleList
+    kegg_ddi(dbentries::Vector{String}) -> KeggTupleList
 
 Find adverse drug-drug interactions (DDI).
 
@@ -13,20 +13,19 @@ The available databases are:
   NDC or YJ code entries to query for interactions.
 
 # Returns
-- `data::KeggTupleList`: A data structure containing the `url`, the `data`
-  retrieved, and the `colnames`. The columns are `["Entry 1", "Entry 2",
-  "Interaction Type", "Mechanism"]`, where the interaction type is `CI`
-  (contraindication) or `P` (precaution).
+- `KeggTupleList`: The interactions, request URL or URLs, and column names. The
+  columns are `["Entry 1", "Entry 2", "Interaction Type", "Mechanism"]`, where
+  the interaction type is `CI` (contraindication) or `P` (precaution).
 
 # Throws
 - `ArgumentError`: If `dbentries` is empty
 
 # Examples
-```julia
-using KEGGAPI
+```jldoctest
+julia> result = kegg_ddi(["D00564", "D00100"]);
 
-KEGGAPI.kegg_ddi("D00564")
-KEGGAPI.kegg_ddi(["D00564", "D00100"])
+julia> result isa KEGGAPI.KeggTupleList && result.colnames == ["Entry 1", "Entry 2", "Interaction Type", "Mechanism"]
+true
 ```
 
 # Extended help
diff --git a/src/Find.jl b/src/Find.jl
index 357538b..e836be3 100644
--- a/src/Find.jl
+++ b/src/Find.jl
@@ -40,16 +40,15 @@ Allowed `option` values (only for the `compound` and `drug` databases):
   chemical field. `nop` disables keyword pre-processing.
 
 # Returns
-- `data::KeggTupleList`: A data structure containing the `url`, the `data`
-  retrieved, and the `colnames`.
+- `KeggTupleList`: The matching identifiers and descriptions, with the request
+  URL and column names.
 
 # Examples
-```julia
-using KEGGAPI
+```jldoctest
+julia> result = kegg_find("compound", "glucose");
 
-KEGGAPI.kegg_find("compound", "glucose")
-KEGGAPI.kegg_find("compound", "C7H10O5", "formula")
-KEGGAPI.kegg_find("ko", "kinase")
+julia> result isa KEGGAPI.KeggTupleList && result.colnames == ["ID", "Details"] && !isempty(result.data)
+true
 ```
 
 # Extended help
diff --git a/src/Get.jl b/src/Get.jl
index a47221a..3590bf5 100644
--- a/src/Get.jl
+++ b/src/Get.jl
@@ -67,8 +67,8 @@ end
 
 # ---------------------------------------------------------------------------- Main function
 """
-    kegg_get(dbentries::Vector{String}, option::Union{Symbol, Nothing} = nothing; request_delay::Real = 0.4, timeout = nothing)
-    kegg_get(dbentry::String, option::Union{Symbol, Nothing} = nothing; request_delay::Real = 0.4, timeout = nothing)
+    kegg_get(dbentries::Vector{String}, option::Union{Symbol, Nothing} = nothing; request_delay::Real = 0.4, timeout = nothing) -> NamedTuple
+    kegg_get(dbentry::String, option::Union{Symbol, Nothing} = nothing; request_delay::Real = 0.4, timeout = nothing) -> NamedTuple
 
 Retrieve given database entries.
 
@@ -99,16 +99,24 @@ Allowed `option` for retrieval of selected fields:
   and `timeout` conflict.
 
 # Returns
-A tuple containing:
-- `url::Vector{String}`: A vector of URLs used for the API requests.
-- `data::Vector{Any}`: A vector of retrieved data corresponding to the provided database
-  entries, processed according to the specified `option`.
+- For vector input, a named tuple `(url = urls, data = data)`. `urls` is a
+  `Vector{String}` containing one URL per request batch. `data` is a vector with
+  one processed result per retrieved entry.
+- For scalar input, a named tuple `(url = url, data = data)`. `url` is the single
+  request URL. `data` is a `String` for text and sequence formats and a
+  `Vector{UInt8}` for `:image` and `:image2x`.
 
-# Example
-```julia-repl
-dbentries = ["hsa:10458", "hsa:10459", "hsa:10460"]
-option = :aaseq
-urls, data = kegg_get(dbentries, option)
+# Examples
+```jldoctest
+julia> result = kegg_get(["hsa:10458", "hsa:10459"], :aaseq);
+
+julia> (result.url isa Vector{String}, length(result.data), all(item -> item isa String, result.data))
+(true, 2, true)
+
+julia> result = kegg_get("hsa:10458");
+
+julia> (result.url isa String, result.data isa String)
+(true, true)
 ```
 
 # Extended help
@@ -174,17 +182,23 @@ function kegg_get(dbentry::String, args...; kwargs...)
 end
 
 """
-    @kegg_str
+    @kegg_str -> NamedTuple
 
 Macro to retrieve a KEGG database entry flat file from a string. This is intended
 for interactive use in the REPL.
 
 See [`kegg_get`](@ref) for more details on allowed database entries.
 
+# Returns
+- `NamedTuple`: The same `(url = url, data = data)` result as scalar
+  [`kegg_get`](@ref).
+
 # Example
-```julia
-using KEGGAPI
-entry = kegg"hsa:10458"
+```jldoctest
+julia> entry = kegg"hsa:10458";
+
+julia> (entry.url isa String, entry.data isa String)
+(true, true)
 ```
 """
 macro kegg_str(dbentry)
diff --git a/src/Info.jl b/src/Info.jl
index efb67be..9a6d105 100644
--- a/src/Info.jl
+++ b/src/Info.jl
@@ -1,5 +1,5 @@
 """
-    KEGGAPI.kegg_info(database::String)
+    kegg_info(database::String) -> String
 
 Get information about a specific database from the KEGG API.
 
@@ -16,23 +16,26 @@ ntmap    | variant | disease | drug    | dgroup
 - `database::String`: The KEGG database for which to retrieve information.
 
 # Returns
-- `data::String`: A string containing the information about the specified database.
+- `String`: Database release information and statistics from KEGG.
 
 # Example
 
-```julia-repl
-KEGGAPI.kegg_info("kegg")
+```jldoctest
+julia> info = kegg_info("kegg");
+
+julia> occursin("KEGG", info)
+true
+```
 
 # Extended help
 
-This operation displays the database release information with statistics for the
-databases shown in the table. Except for :kegg, :genes and :ligand, this operation
-also retrieves the list of linked databases that can be used in the link operation.
+This operation displays database release information and statistics. Except for
+`kegg`, `genes`, and `ligand`, it also returns the linked databases accepted by
+[`kegg_link`](@ref).
 
 # Reference
 
 - https://www.kegg.jp/kegg/rest/keggapi.html#info
-```
 """
 function kegg_info(database::String)
     url = "https://rest.kegg.jp/info/$database"
diff --git a/src/Link.jl b/src/Link.jl
index f7243c8..2b2fd50 100644
--- a/src/Link.jl
+++ b/src/Link.jl
@@ -5,7 +5,7 @@ const KEGG_LINK_RDF_OPTIONS = ("turtle", "n-triple")
 
 # ---------------------------------------------------------------------------- Main functions
 """
-    kegg_link(target_db::String, source_db::String, option::String = "")
+    kegg_link(target_db::String, source_db::String, option::String = "") -> Union{KeggTupleList, String}
 
 Find related entries by using database cross-references.
 
@@ -29,12 +29,22 @@ and the available external databases are:
   requested (`turtle | n-triple`), in which case the raw response text is
   returned instead of a `KeggTupleList`.
 
+# Returns
+- `KeggTupleList`: The linked identifiers, request URL, and column names for
+  tabular responses.
+- `String`: The raw RDF response when `option` is `"turtle"` or `"n-triple"`.
+
 # Examples
-```julia
-using KEGGAPI
+```jldoctest
+julia> links = kegg_link("pathway", "hsa:10458");
+
+julia> links isa KEGGAPI.KeggTupleList && !isempty(links.data)
+true
 
-KEGGAPI.kegg_link("pathway", "hsa")
-KEGGAPI.kegg_link("atc", "D00564", "turtle")   # raw RDF (turtle) String
+julia> rdf = kegg_link("atc", "D00564", "turtle");
+
+julia> rdf isa String && !isempty(rdf)
+true
 ```
 
 # Extended help
@@ -53,7 +63,7 @@ function kegg_link(target_db::String, source_db::String, option::String = "")
 end
 
 """
-    kegg_link(target_db::String, dbentries::Vector{String}, option::String = ""; request_delay::Real = 0.4, timeout = nothing)
+    kegg_link(target_db::String, dbentries::Vector{String}, option::String = ""; request_delay::Real = 0.4, timeout = nothing) -> Union{KeggTupleList, String}
 
 Find related entries by using database cross-references.
 
@@ -81,10 +91,24 @@ and the available external databases are:
 - `timeout::Real`, deprecated alias for `request_delay`. If both keywords are
   supplied, their values must be equal.
 
+# Returns
+- `KeggTupleList`: The linked identifiers, request URLs, and column names for
+  tabular responses.
+- `String`: The concatenated raw RDF responses when `option` is `"turtle"` or
+  `"n-triple"`.
+
 # Throws
 - `ArgumentError`: If a delay is negative or non-finite, or if `request_delay`
   and `timeout` conflict.
 
+# Examples
+```jldoctest
+julia> links = kegg_link("pathway", ["hsa:10458", "hsa:10459"]);
+
+julia> links isa KEGGAPI.KeggTupleList && links.url isa Vector{String} && !isempty(links.data)
+true
+```
+
 The vector form sends at most 10 entries per request. It waits `request_delay`
 seconds between requests, but does not wait after the final request.
 """
diff --git a/src/List.jl b/src/List.jl
index cfab760..f7e2649 100644
--- a/src/List.jl
+++ b/src/List.jl
@@ -1,7 +1,12 @@
 """
     kegg_list(query::String, query_type::String = "") -> Union{KeggTupleList, KeggGenesList}
 
-Get a list of entry identifiers and associated names
+Get a list of entry identifiers and associated names.
+
+# Arguments
+- `query::String`: The KEGG database to list.
+- `query_type::String`: An optional organism code, BRITE prefix, organism group,
+  or taxonomy rank identifier used to narrow the list.
 
 Allowed `database` values are:
 ```
@@ -13,9 +18,18 @@ drug     | dgroup
 
 # Returns
 
-- `KeggTupleList`: Rows from a two-column response, a response with an
-  unrecognized width, or an empty response.
-- `KeggGenesList`: The four columns in an organism-specific gene response.
+- `KeggTupleList`: A two-column response, a response with an unrecognized width,
+  or an empty response, together with its request URL and column names.
+- `KeggGenesList`: The four columns in an organism-specific gene response,
+  together with its request URL and column names.
+
+# Examples
+```jldoctest
+julia> result = kegg_list("pathway", "hsa");
+
+julia> result isa KEGGAPI.KeggTupleList && !isempty(result.data)
+true
+```
 
 # Extended help
 
@@ -33,7 +47,6 @@ family, genus, or species identifier.
 # References
 
 - https://www.kegg.jp/kegg/rest/keggapi.html#list
-```
 """
 function kegg_list(query::String, query_type::String = "")
     return _kegg_list(query, query_type, request)
@@ -49,7 +62,7 @@ end
 """
     kegg_list(dbentries::Vector{String}; request_delay::Real = 0.4, timeout = nothing) -> KeggTupleList
 
-Get a list of entry identifiers and associated names
+Get a list of entry identifiers and associated names.
 
 # Arguments
 - `dbentries::Vector{String}`: The list of entries to list.
@@ -63,8 +76,15 @@ Get a list of entry identifiers and associated names
   and `timeout` conflict.
 
 # Returns
-- `data::KeggTupleList`: A data structure containing the `url`, the `data` retrieved,
-  and the `columns` names for the data.
+- `KeggTupleList`: The requested entries, request URLs, and column names.
+
+# Examples
+```jldoctest
+julia> result = kegg_list(["hsa:10458", "hsa:10459"]);
+
+julia> result isa KEGGAPI.KeggTupleList && result.url isa Vector{String} && length(result.data) == 2
+true
+```
 
 # Extended help
 
diff --git a/src/Requests.jl b/src/Requests.jl
index 5417b70..68b4924 100644
--- a/src/Requests.jl
+++ b/src/Requests.jl
@@ -18,9 +18,16 @@ error or response in their fields.
 # Examples
 `request` is not exported, so call it with the `KEGGAPI` module prefix.
 
-```julia
-text = KEGGAPI.request("https://rest.kegg.jp/info/kegg")
-image = KEGGAPI.request("https://rest.kegg.jp/get/hsa00010/image", Vector{UInt8})
+```jldoctest
+julia> text = KEGGAPI.request("https://rest.kegg.jp/info/kegg");
+
+julia> occursin("KEGG", text)
+true
+
+julia> image = KEGGAPI.request("https://rest.kegg.jp/get/hsa00010/image", Vector{UInt8});
+
+julia> image[1:8] == UInt8[0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]
+true
 ```
 
 # Arguments

From 5f64111578a051c766483395f928f66bd9710e75 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Carlos=20Vigil-V=C3=A1squez?= <carlos.vigil.v@gmail.com>
Date: Wed, 16 Sep 2026 22:36:36 +0200
Subject: [PATCH 2/2] docs: tighten package prose

---
 README.md                       |  9 +++---
 benchmarking/README.md          | 50 ++++++++++++++++-----------------
 docs/src/index.md               | 16 +++++------
 docs/src/man/examples.md        |  8 +++---
 docs/src/man/getting-started.md | 13 ++++-----
 docs/src/man/usecases/case1.md  | 13 ++++-----
 docs/src/man/usecases/case2.md  | 10 +++----
 docs/src/man/usecases/case3.md  | 11 ++++----
 docs/src/man/usecases/case4.md  | 13 ++++-----
 src/Conv.jl                     | 10 +++----
 src/Ddi.jl                      |  7 ++---
 src/Find.jl                     | 13 ++++-----
 src/Get.jl                      | 27 ++++++++----------
 src/Info.jl                     |  6 ++--
 src/Link.jl                     |  9 +++---
 src/List.jl                     |  7 ++---
 src/Requests.jl                 |  4 +--
 17 files changed, 106 insertions(+), 120 deletions(-)

diff --git a/README.md b/README.md
index 26c4eb1..fb3f881 100644
--- a/README.md
+++ b/README.md
@@ -7,8 +7,7 @@
 [![code style: runic](https://img.shields.io/badge/code_style-%E1%9A%B1%E1%9A%A2%E1%9A%BE%E1%9B%81%E1%9A%B2-black)](https://github.com/fredrikekre/Runic.jl)
 [![DOI](https://zenodo.org/badge/667588694.svg)](https://doi.org/10.5281/zenodo.22282089)
 
-
-KEGGAPI.jl is a Julia package for accesing the Kyoto Encyclopedia of Genes and Genomes, striving to take advantage of the speed and flexibility that Julia offers and make it accessible to the bioinformatics and functional annotation communities.
+KEGGAPI.jl is a Julia client for the [Kyoto Encyclopedia of Genes and Genomes](https://www.kegg.jp/) REST API.
 
 ## KEGG usage terms
 
@@ -54,7 +53,7 @@ entries = ["hsa:$id" for id in 10458:10468]
 result = kegg_get(entries; request_delay = 0.5)
 ```
 
-The old `timeout` keyword remains available as a deprecated alias.
+The deprecated `timeout` keyword remains available as an alias for `request_delay`.
 
 ## Documentation
 
@@ -62,14 +61,14 @@ The old `timeout` keyword remains available as a deprecated alias.
 - [Examples](https://cvigilv.github.io/KEGGAPI.jl/dev/man/examples/)
 - [API reference](https://cvigilv.github.io/KEGGAPI.jl/dev/man/api/)
 
-Worked end-to-end use cases:
+Worked use cases:
 
 - [Case 1: From a UniProt ID to KEGG information](https://cvigilv.github.io/KEGGAPI.jl/dev/man/usecases/case1/)
 - [Case 2: EC reaction information in KEGG](https://cvigilv.github.io/KEGGAPI.jl/dev/man/usecases/case2/)
 - [Case 3: Identifying a compound in KEGG](https://cvigilv.github.io/KEGGAPI.jl/dev/man/usecases/case3/)
 - [Case 4: Target molecule information at KEGG](https://cvigilv.github.io/KEGGAPI.jl/dev/man/usecases/case4/)
 
-## Speed Tests
+## Benchmarks
 
 ![KEGGAPI.jl Benchmarks](benchmarking/benchmark.svg "KEGGAPI.jl Benchmarks")
 
diff --git a/benchmarking/README.md b/benchmarking/README.md
index 4788c8a..8aadc87 100644
--- a/benchmarking/README.md
+++ b/benchmarking/README.md
@@ -1,7 +1,7 @@
 # Benchmarking
 
-Compares `KEGGAPI.jl` against the other common KEGG REST clients — `KEGGREST`
-(R), `Bio.KEGG.REST` (Python) and raw `curl` — across the KEGG operations:
+This benchmark compares `KEGGAPI.jl`, `KEGGREST` for R, `Bio.KEGG.REST` for
+Python, and raw `curl` across these KEGG operations:
 
 | Operation | Query                          | Covered by            |
 |:----------|:-------------------------------|:----------------------|
@@ -14,18 +14,18 @@ Compares `KEGGAPI.jl` against the other common KEGG REST clients — `KEGGREST`
 | `Link`    | `link/pathway/hsa:10458`       | all                   |
 | `Ddi`     | `ddi/D00564`                   | KEGGAPI.jl, curl only |
 
-`ddi` has no wrapper in KEGGREST or Bio.KEGG.REST, so those interfaces simply
-have no bar for it in the figure. The `conv` case uses `ncbi-geneid` rather than
+KEGGREST and Bio.KEGG.REST do not wrap `ddi`, so the figure omits their bars for
+that operation. The `conv` case uses `ncbi-geneid` rather than
 `ncbi-proteinid` because Bio.KEGG.REST only recognises the legacy outside-database
 names (`ncbi-gi | ncbi-geneid | uniprot`) and rejects the newer ones.
 
 `KEGGAPI.jl`'s chunked `kegg_get` waits between requests to respect KEGG's rate
-limit. The Julia runner passes `request_delay = 0.0` because the runner already
-spaces its own calls and should not include that delay in its timings.
+limit. The Julia runner passes `request_delay = 0.0` because it already spaces
+calls and must not time the same delay twice.
 
-Each interface runs every operation inside a **single** process, so what is
-measured is per-call time rather than interpreter startup. A warm-up call is
-discarded before the measured replicates, and calls are spaced by `--pause`
+Each interface runs every operation in one process, which excludes interpreter
+startup from the measurements. The runner discards a warm-up call before the
+measured replicates and spaces calls by `--pause`
 seconds (default 0.4 s) to stay under KEGG's limit of 3 requests per second.
 
 ## Running
@@ -50,8 +50,8 @@ julia --project=benchmarking benchmarking/plot_benchmarks.jl
 
 ## Optional interfaces
 
-Only Julia and `curl` are required. Interfaces whose dependencies are missing
-are reported and skipped, so the run always completes. To include the others:
+Only Julia and `curl` are required. The script reports and skips interfaces
+whose dependencies are missing. To include the others:
 
 ```bash
 # R (KEGGREST via Bioconductor)
@@ -64,12 +64,12 @@ python3 -m venv /tmp/kegg_bench_venv
 
 ### Nix-provided R
 
-A nix R installs packages from source but does not expose its dependency paths
-to those builds, so CRAN/Bioconductor sources fail to link (`library not found
+A Nix-provided R installs packages from source but does not expose its dependency
+paths to those builds, so CRAN/Bioconductor sources fail to link (`library not found
 for -lintl`, `zlib.h not found`, `-lldap`, `-lkrb5`). Point `R_MAKEVARS_USER` at
-a Makevars supplying the paths — adjust the store hashes to match your system,
-which `otool -L $(R RHOME)/lib/libR.dylib` and `ls -d /nix/store/*<pkg>*` will
-tell you:
+a Makevars supplying the paths. Adjust the store hashes to match your system.
+Find them with `otool -L $(R RHOME)/lib/libR.dylib` and
+`ls -d /nix/store/*<pkg>*`:
 
 ```make
 GETTEXT  = /nix/store/...-gettext-0.22.5
@@ -89,13 +89,14 @@ R_MAKEVARS_USER=/path/to/Makevars \
   Rscript -e 'BiocManager::install("KEGGREST", ask = FALSE, update = FALSE)'
 ```
 
-Using `R_MAKEVARS_USER` keeps this out of `~/.R/Makevars`, so it applies only to
-the install. It is not needed to *run* the benchmark, only to build the packages.
+`R_MAKEVARS_USER` applies the settings only to this installation instead of
+writing them to `~/.R/Makevars`. The benchmark does not need it after the
+packages are built.
 
 ### Selecting interpreters
 
-The `JULIA`, `RSCRIPT` and `PYTHON` environment variables override which
-interpreter is used, which is how a virtualenv is selected:
+Set `JULIA`, `RSCRIPT`, or `PYTHON` to select an interpreter. For example, use
+`PYTHON` to select a virtual environment:
 
 ```bash
 PYTHON=/tmp/kegg_bench_venv/bin/python \
@@ -113,13 +114,12 @@ PYTHON=/tmp/kegg_bench_venv/bin/python \
 | `runners/bench_python.py`| Bio.KEGG.REST timings                               |
 | `runners/bench_curl.sh`  | Raw REST timings via `curl -w %{time_total}`        |
 
-Each runner prints `Function,Language,seconds` — one row per replicate — so it
-can also be run on its own, e.g.:
+Each runner prints one `Function,Language,seconds` row per replicate. Run an
+individual runner with:
 
 ```bash
 julia --project=benchmarking benchmarking/runners/bench_julia.jl 5 0.4
 ```
 
-> **Note:** results are dominated by network round-trip time to `rest.kegg.jp`
-> and will vary with location and server load. Compare interfaces within a
-> single run rather than across runs.
+Network round-trip time to `rest.kegg.jp` dominates these results. Compare
+interfaces within one run because location and server load vary between runs.
diff --git a/docs/src/index.md b/docs/src/index.md
index 64266ea..84e97aa 100644
--- a/docs/src/index.md
+++ b/docs/src/index.md
@@ -3,10 +3,9 @@ CurrentModule = KEGGAPI
 ```
 # KEGGAPI.jl
 
-A Julia interface for the [KEGG API](https://www.kegg.jp/kegg/rest/keggapi.html).
-The interface allows the functional annotation of genes, identification of metabolic processes
-and pathways, the exploration of reaction/pathway prevalence at different taxonomic levels and
-the identification of orthologous proteins for further analysis.
+KEGGAPI.jl is a Julia client for the [KEGG REST API](https://www.kegg.jp/kegg/rest/keggapi.html).
+It retrieves KEGG entries, sequences, images, database links, identifier conversions, and
+drug-drug interactions.
 
 ## KEGG usage terms
 
@@ -18,8 +17,7 @@ non-academic use.
 KEGGAPI.jl's MIT license covers only the Julia client code. It does not grant any rights to KEGG
 data or services.
 
-KEGGAPI.jl aims to support all KEGG API endpoints provided by the
-["KEGGREST"](https://bioconductor.org/packages/release/bioc/html/KEGGREST.html) package for R
-(Tenenbaum and maintainers, 2025) and the
-["Bio.KEGG.REST"](https://biopython.org/docs/1.75/api/Bio.KEGG.REST.html) submodule from
-Biopython for Python.
+Its endpoint coverage follows
+[KEGGREST](https://bioconductor.org/packages/release/bioc/html/KEGGREST.html) for R
+(Tenenbaum and maintainers, 2025) and
+[Bio.KEGG.REST](https://biopython.org/docs/1.75/api/Bio.KEGG.REST.html) for Python.
diff --git a/docs/src/man/examples.md b/docs/src/man/examples.md
index 206abfd..698ba17 100644
--- a/docs/src/man/examples.md
+++ b/docs/src/man/examples.md
@@ -2,10 +2,10 @@
 
 ## `kegg_conv`
 
-These examples follow the [KEGG Conv](https://www.kegg.jp/kegg/rest/keggapi.html#conv)
-operation. `kegg_conv` returns a `KeggTupleList` containing the request URL,
-column names, and data. Pass the latter two fields to `DataFrame` to construct a
-data frame:
+These examples call the [KEGG Conv](https://www.kegg.jp/kegg/rest/keggapi.html#conv)
+operation. `kegg_conv` returns the request URL, column names, and data in a
+`KeggTupleList`. Construct a `DataFrame` from `output.data` and
+`output.colnames`:
 
 ```@setup examples
 using KEGGAPI
diff --git a/docs/src/man/getting-started.md b/docs/src/man/getting-started.md
index b1bd223..d98eef8 100644
--- a/docs/src/man/getting-started.md
+++ b/docs/src/man/getting-started.md
@@ -2,8 +2,7 @@
 
 ## Installation
 
-KEGGAPI.jl can be installed using the Julia package manager.
-From the Julia REPL, type `]` to enter the Pkg REPL mode and run
+From the Julia REPL, type `]` to enter the Pkg REPL and install KEGGAPI.jl:
 
 ```
 pkg> add KEGGAPI
@@ -17,8 +16,8 @@ Load KEGGAPI.jl with `using`:
 using KEGGAPI
 ```
 
-Then call a wrapper for the KEGG operation you need. For example, list all
-organisms in KEGG:
+Each wrapper is named after its KEGG operation. This call lists all organisms in
+KEGG:
 
 ```@example examples
 result = KEGGAPI.kegg_list("genome")
@@ -26,8 +25,8 @@ result = KEGGAPI.kegg_list("genome")
 nothing # hide
 ```
 
-This returns a `KeggTupleList` containing the request URL, column names, and data.
-Access them through the corresponding fields:
+The result contains the request URL, column names, and data:
+
 ```@example examples
 result.url
 ```
@@ -48,4 +47,4 @@ KEGGAPI lets HTTP.jl exceptions propagate. An unsuccessful HTTP response throws
 `HTTP.Exceptions.TimeoutError`, respectively. See [`KEGGAPI.request`](@ref) for
 the low-level request contract.
 
-For more example usage, refer to the [examples](examples.md) page and the [API reference](api.md).
+See [Examples](examples.md) for more calls and [API reference](api.md) for the full interface.
diff --git a/docs/src/man/usecases/case1.md b/docs/src/man/usecases/case1.md
index 2456ea2..31359ab 100644
--- a/docs/src/man/usecases/case1.md
+++ b/docs/src/man/usecases/case1.md
@@ -1,8 +1,7 @@
 # Case 1: From a UniProt ID to KEGG information
 
-This walkthrough starts from a protein identifier in an outside database
-(UniProt / Swiss-Prot) and pulls together the corresponding KEGG gene, its
-sequences, orthology group, reactions and pathways.
+This walkthrough starts with a UniProt identifier and retrieves its KEGG gene,
+sequences, orthology group, reactions, and pathways.
 
 ```@setup case1
 using KEGGAPI
@@ -40,7 +39,7 @@ conv = KEGGAPI.kegg_conv("genes", entries)
 conv.url
 ```
 
-The reverse direction (KEGG → outside database) works the same way:
+To convert from KEGG to an outside database, reverse the target and source:
 
 ```@example case1
 conv = KEGGAPI.kegg_conv("ncbi-proteinid", "mtr:25493984")
@@ -111,9 +110,9 @@ ko_genes = KEGGAPI.kegg_link("genes", "K01183")
 first(DataFrame(ko_genes.data, ko_genes.colnames), 5)
 ```
 
-The second column of `ko_genes.data` is a vector of gene identifiers that can be
-fed straight back into `kegg_get(...; :aaseq)` or `:ntseq` to build, for example,
-a multiple-sequence-alignment input.
+The second column of `ko_genes.data` contains gene identifiers. Pass it to
+`kegg_get` with `:aaseq` or `:ntseq` to prepare input for a multiple sequence
+alignment.
 
 ## 6. Download a pathway map
 
diff --git a/docs/src/man/usecases/case2.md b/docs/src/man/usecases/case2.md
index c409cbc..8d773c1 100644
--- a/docs/src/man/usecases/case2.md
+++ b/docs/src/man/usecases/case2.md
@@ -1,7 +1,7 @@
 # Case 2: EC reaction information in KEGG
 
-Starting from an Enzyme Commission (EC) number, this walkthrough finds the
-associated KEGG reactions, their compounds, and the orthology group.
+This walkthrough uses an Enzyme Commission (EC) number to find KEGG reactions,
+their compounds, and the associated orthology group.
 
 ```@setup case2
 using KEGGAPI
@@ -21,9 +21,9 @@ DataFrame(rxns.data, rxns.colnames)
 
 ## 2. Reaction information
 
-The second column of `rxns.data` holds the reaction identifiers (`rn:R…`). Pass
-them to [`kegg_get`](@ref) to retrieve the full entries; `.data` is a vector with
-one flat-file `String` per reaction:
+The second column of `rxns.data` holds the reaction identifiers, such as
+`rn:R01206`. Pass them to [`kegg_get`](@ref) to retrieve the full entries. The
+`.data` field contains one flat-file `String` per reaction:
 
 ```@example case2
 info = KEGGAPI.kegg_get(rxns.data[2])
diff --git a/docs/src/man/usecases/case3.md b/docs/src/man/usecases/case3.md
index 9339c66..d85b7d3 100644
--- a/docs/src/man/usecases/case3.md
+++ b/docs/src/man/usecases/case3.md
@@ -21,8 +21,8 @@ DataFrame(hits.data, hits.colnames)
 
 ## 2. Retrieve the compound entry
 
-The first column of `hits.data` holds the compound identifiers (`cpd:C…`). Fetch
-the full entry with [`kegg_get`](@ref):
+The first column of `hits.data` holds compound identifiers such as `cpd:C00461`.
+Fetch the full entry with [`kegg_get`](@ref):
 
 ```@example case3
 cpd = KEGGAPI.kegg_get("cpd:C00461")
@@ -48,8 +48,7 @@ bytes_written == length(img.data)
 
 ## 4. Reactions linked to the compound
 
-[`kegg_link`](@ref) returns one row for every reaction the compound takes part
-in:
+[`kegg_link`](@ref) returns the reactions that include the compound:
 
 ```@example case3
 rxns = KEGGAPI.kegg_link("reaction", "cpd:C00461")
@@ -59,8 +58,8 @@ DataFrame(rxns.data, rxns.colnames)
 
 ## 5. Reaction information
 
-Feed the reaction identifiers (the second column of `rxns.data`) back into
-`kegg_get` to retrieve their entries:
+Pass the reaction identifiers in the second column of `rxns.data` to `kegg_get`
+to retrieve their entries:
 
 ```@example case3
 info = KEGGAPI.kegg_get(rxns.data[2])
diff --git a/docs/src/man/usecases/case4.md b/docs/src/man/usecases/case4.md
index bf38fa4..998d50a 100644
--- a/docs/src/man/usecases/case4.md
+++ b/docs/src/man/usecases/case4.md
@@ -1,7 +1,7 @@
 # Case 4: Target molecule information at KEGG
 
-Starting from a target molecule name, this walkthrough finds the encoding gene
-and then explores its orthology group, pathways and associated drugs.
+This walkthrough searches for a target molecule's gene, then retrieves its
+orthology group, pathways, and associated drugs.
 
 ```@setup case4
 using KEGGAPI
@@ -11,8 +11,8 @@ using DataFrames
 ## 1. Find the gene for a target molecule
 
 [`kegg_find`](@ref) with the `genes` database searches gene names and
-descriptions. A popular target such as `CD19` matches many organisms, so we show
-only the first few hits:
+descriptions. `CD19` matches genes from many organisms, so this example shows
+only the first five hits:
 
 ```@example case4
 genes = KEGGAPI.kegg_find("genes", "CD19")
@@ -30,7 +30,7 @@ gene = KEGGAPI.kegg_get("hsa:930")
 println(join(first(split(gene.data, "\n"), 8), "\n"))
 ```
 
-Its orthology (KO) group via [`kegg_link`](@ref):
+Use [`kegg_link`](@ref) to retrieve its orthology (KO) group:
 
 ```@example case4
 ko = KEGGAPI.kegg_link("ko", "hsa:930")
@@ -54,8 +54,7 @@ drugs = KEGGAPI.kegg_link("drug", "hsa:930")
 DataFrame(drugs.data, drugs.colnames)
 ```
 
-Retrieve information on the associated drugs by passing their identifiers (the
-second column of `drugs.data`) to `kegg_get`:
+Pass the drug identifiers in the second column of `drugs.data` to `kegg_get`:
 
 ```@example case4
 drug_info = KEGGAPI.kegg_get(drugs.data[2])
diff --git a/src/Conv.jl b/src/Conv.jl
index 2bc4ab7..6fe12bd 100644
--- a/src/Conv.jl
+++ b/src/Conv.jl
@@ -21,10 +21,10 @@ true
 
 # Extended help
 
-This operation can be used to convert entry identifiers (accession numbers) of outside databases
-to KEGG identifiers, and vice versa. The first form allows database to database mapping, while
-the second form allows conversion of a selected number of entries. The database name "genes" may
-be used only in the second form.
+Convert outside accession numbers to KEGG identifiers or KEGG identifiers to
+outside accession numbers. Pass database names for database-to-database mapping,
+or pass one or more entries to convert selected identifiers. The `genes`
+database is valid only when converting selected entries.
 
 ## References
 
@@ -57,7 +57,7 @@ For chemical substance identifiers:
 
 # Arguments
 - `target_db::String`: Target database
-- `dbentries::Vector{String}`: Database entries of the available databases
+- `dbentries::Vector{String}`: Entries to convert.
 - `request_delay::Real`: Seconds to wait between batched requests. Defaults to
   0.4. No delay occurs when the input fits in one request.
 - `timeout::Real`: Deprecated alias for `request_delay`. If both keywords are
diff --git a/src/Ddi.jl b/src/Ddi.jl
index a79ed4d..0eda81e 100644
--- a/src/Ddi.jl
+++ b/src/Ddi.jl
@@ -30,10 +30,9 @@ true
 
 # Extended help
 
-This operation searches against the KEGG DDI database, which contains known
-adverse drug-drug interactions. When multiple entries are given, all pairwise
-interactions among them are also reported. Vector inputs must contain between one
-and ten entries. Empty vectors and vectors with more than ten entries throw an
+The KEGG DDI database records known adverse drug-drug interactions. A query with
+multiple entries also returns pairwise interactions among those entries. Vector
+inputs must contain between one and ten entries. Empty vectors and vectors with more than ten entries throw an
 `ArgumentError` before a request is sent. Queries above the KEGG limit cannot be
 split into independent requests because doing so would omit interactions between
 entries in different requests.
diff --git a/src/Find.jl b/src/Find.jl
index e836be3..4c9585f 100644
--- a/src/Find.jl
+++ b/src/Find.jl
@@ -53,13 +53,12 @@ true
 
 # Extended help
 
-This operation searches KEGG databases for entries matching the given query. The
-`option` argument is only meaningful for chemical databases (`compound`, `drug`)
-and is used to search by molecular `formula`, `exact_mass` or `mol_weight`
-(ranges may be given with a minus sign, e.g. `"300-310"`); `nop` disables the
-keyword pre-processing. Any recognized KEGG database (or an organism code) is
-accepted; unrecognized database names emit a warning but are still passed through
-to the API.
+`kegg_find` searches a KEGG database for entries that match `query`. For
+`compound` and `drug`, use `option` to search by `formula`, `exact_mass`, or
+`mol_weight`. Specify a range with a hyphen, as in `"300-310"`. The `nop` option
+disables keyword preprocessing. The function accepts recognized KEGG databases
+and organism codes. It warns about other database names before passing them to
+the API.
 
 # Reference
 
diff --git a/src/Get.jl b/src/Get.jl
index 3590bf5..ddf1054 100644
--- a/src/Get.jl
+++ b/src/Get.jl
@@ -121,18 +121,16 @@ julia> (result.url isa String, result.data isa String)
 
 # Extended help
 
-This operation retrieves given database entries in a flat file format or in other
-formats with `option`. Flat file formats are available for all KEGG databases
-except brite. The input is limited up to 10 entries; if more are provided the
-query is split into chunks of 10 entries. The function waits `request_delay`
-seconds between requests, but does not wait after the final request. The default
-of 0.4 seconds keeps batched calls below KEGG's limit of three requests per
-second.
-
-Options allow retrieval of selected fields, including sequence data from genes
-entries, chemical structure data or GIF image files from compound, glycan and
-drug entries, PNG image files or KGML files from pathway entries. The `:image2x`
-option retrieves the doubled-size PNG image of a reference pathway map.
+`kegg_get` retrieves entries as KEGG flat files or in the format selected by
+`option`. Flat files are supported for every KEGG database except `brite`. Each
+request accepts at most 10 entries, so the function splits longer inputs into
+batches. It waits `request_delay` seconds between batches but not after the final
+request. The default of 0.4 seconds keeps batched calls below KEGG's limit of
+three requests per second.
+
+Use `option` to retrieve gene sequences, chemical structures, compound, glycan,
+or drug images, pathway images, or KGML files. The `:image2x` option retrieves a
+reference pathway map at double size.
 
 The input is limited to **one compound/glycan/drug entry with the `:image` option**,
 and to **one pathway entry with the `:image`, `:image2x` or `:kgml` option**.
@@ -184,10 +182,9 @@ end
 """
     @kegg_str -> NamedTuple
 
-Macro to retrieve a KEGG database entry flat file from a string. This is intended
-for interactive use in the REPL.
+Retrieve a KEGG flat-file entry with string-macro syntax in the REPL.
 
-See [`kegg_get`](@ref) for more details on allowed database entries.
+See [`kegg_get`](@ref) for accepted database entries.
 
 # Returns
 - `NamedTuple`: The same `(url = url, data = data)` result as scalar
diff --git a/src/Info.jl b/src/Info.jl
index 9a6d105..cb1c11a 100644
--- a/src/Info.jl
+++ b/src/Info.jl
@@ -29,9 +29,9 @@ true
 
 # Extended help
 
-This operation displays database release information and statistics. Except for
-`kegg`, `genes`, and `ligand`, it also returns the linked databases accepted by
-[`kegg_link`](@ref).
+`kegg_info` returns database release information and statistics. For databases
+other than `kegg`, `genes`, and `ligand`, the response also lists databases that
+can be passed to [`kegg_link`](@ref).
 
 # Reference
 
diff --git a/src/Link.jl b/src/Link.jl
index 2b2fd50..bc71914 100644
--- a/src/Link.jl
+++ b/src/Link.jl
@@ -49,10 +49,9 @@ true
 
 # Extended help
 
-This operation allows retrieval of cross-references within all KEGG databases, as
-well as between KEGG databases and outside databases. It is useful for finding
-various relationships, such as relationships between genes and pathways. This form
-allows retrieval of database to database cross-references.
+`kegg_link` retrieves cross-references within KEGG and between KEGG and outside
+databases. Pass database names to retrieve all links between two databases, or
+pass entry identifiers to retrieve links for selected entries.
 """
 function kegg_link(target_db::String, source_db::String, option::String = "")
     option_str = isempty(option) ? "" : "/$option"
@@ -81,7 +80,7 @@ and the available external databases are:
 # Arguments
 
 - `target_db::String`, target database
-- `dbentries::Vector{String}`, KEGG database entries of the available databases
+- `dbentries::Vector{String}`, entries from the source database
 - `option::String`, optional refinement of the query. A taxonomic rank
   (`species | genus | family | order | class | phylum`) for `genome`/`taxonomy`
   links, or an RDF output format (`turtle | n-triple`) for the `drug`/`atc`/`jtc`
diff --git a/src/List.jl b/src/List.jl
index f7e2649..8985fa7 100644
--- a/src/List.jl
+++ b/src/List.jl
@@ -33,10 +33,9 @@ true
 
 # Extended help
 
-This operation can be used to obtain a list of all entries in each database. The
-database names shown in the tables above, excluding the composite database names
-of genes and kegg, may be given. To obtain a list of KEGG organisms with their
-three- or four-letter organism codes, use the `genome` database.
+`kegg_list` returns entries from the requested database. It accepts the database
+names above except the composite databases `genes` and `kegg`. Use `genome` to
+list organisms and their three- or four-letter codes.
 
 The optional `query_type` becomes the second URL segment. For pathway queries,
 pass an organism code to list organism-specific pathways. For BRITE queries,
diff --git a/src/Requests.jl b/src/Requests.jl
index 68b4924..c576f8e 100644
--- a/src/Requests.jl
+++ b/src/Requests.jl
@@ -8,8 +8,8 @@ The default `T` is `String`. Pass `Vector{UInt8}` to return the response body as
 raw bytes, for example when requesting an image. Other response types must be
 constructible from a `Vector{UInt8}`.
 
-This function uses HTTP.jl's exception behavior. Connection failures, including
-DNS and TLS failures, throw `HTTP.Exceptions.ConnectError`. Failures while
+HTTP.jl exceptions pass through unchanged. Connection failures, including DNS
+and TLS failures, throw `HTTP.Exceptions.ConnectError`. Failures while
 sending a request or reading its response throw `HTTP.Exceptions.RequestError`,
 timeouts throw `HTTP.Exceptions.TimeoutError`, and unsuccessful HTTP responses
 throw `HTTP.Exceptions.StatusError`. The HTTP exceptions retain the underlying