davsclaus opened a new pull request, #26917:
URL: https://github.com/apache/camel/pull/26917
The answer of `camel_catalog_doc` for a component is its description,
syntax, usage line, Maven coordinates and option list. An option list can only
say what can be *set*: syntax that is not an option is invisible in it.
The `sql` component is the clearest case. That a named parameter is written
`:#name` (or `:#${simple}`) appears nowhere in its 15 KB of options:
- `allowNamedParameters` — "Whether to allow using named parameters in the
queries."
- under another option — "Notice if you use named parameters, then a Map
type is used instead."
Neither says what a named parameter looks like. The component's page
explains it fully in its first 80 lines, but that page was reachable only
through `includeDoc`, which returns all of it and is off by default — so an
author who does not already know the answer has no reason to ask for it.
The answer now carries the page's prose from its first section, trimmed to
1400 characters, with a hint that `includeDoc=true` gives the rest. For `sql`
that is 1377 characters containing `:#name_of_the_parameter`, the lookup
precedence and the `$simple{}` form — the essentials, without the option tables.
What the excerpt leaves out, so it is prose rather than markup:
- the title and attribute header of the page, and the Maven dependency
stanza (the answer already has the description and the coordinates);
- `include::` directives, which pull in the generated option tables the
answer already carries as options;
- block decoration such as `[tabs]`, `[TIP]`, `====`, `|===` and `[cols=]`;
- a cross-reference is reduced to the words it links, so
`xref:languages:simple-language.adoc[Simple]` reads as `Simple`.
Code inside a `----` fence is kept, since that is where a component page
shows its URI.
Asking for the whole page with `includeDoc=true` does not also send the
excerpt.
Tests: `CatalogDocExcerptTest` (7) — the sql named-parameter syntax is in
the answer; the excerpt is prose and not AsciiDoc plumbing; it stays within its
budget for sql, kafka, timer, file and http; `includeDoc=true` does not
duplicate; a component with no page is still answered; the excerpt starts at
the first section and drops the dependency stanza; code inside a fence
survives. The 271 tests of the `ai` tool package are green, and a full reactor
build.
Scope: components only. Data formats and languages have the same gap, and
`languageDoc` already has its own `docPage` mechanism for `simple`, so each
deserves its own calibration rather than one budget for all three.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_01Bp3538HRBPMQkb5ta9xRaj
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
