gnodet-bot commented on code in PR #29943: URL: https://github.com/apache/camel/pull/29943#discussion_r4574562091
########## tasks/component-descriptions.md: ########## @@ -0,0 +1,397 @@ +# Component and option descriptions (CAMEL-23832) + +[CAMEL-23832](https://issues.apache.org/jira/browse/CAMEL-23832) improves the description of every component option and +the description of what each component does. The goal is clarity for people and AI tools. The EIPs already have improved +descriptions. + +This file tracks which components are done. Anyone, person or agent, can take a component that is not done yet. The +ticket is shared, so leave it unassigned. + +## Taking a component + +1. Pick a component from the table that has nothing in the "Done" column. Pick at random rather than from the top of the + table, so that people don't start on the same one. +2. Check the + [open pull requests for CAMEL-23832](https://github.com/apache/camel/pulls?q=is%3Apr+is%3Aopen+CAMEL-23832), so that + you don't take a component that is already in progress. +3. Open one pull request per component, with CAMEL-23832 in the title. In the same pull request, write `yes` in the + "Done" column of the component. If the pull request covers only some of its schemes, write those schemes instead. + +## What to change + +- Rewrite the option and header descriptions that are wrong, empty, cut off or unclear. Leave a description that is + correct and clear as it is. +- Put each new text in the `description` attribute of `@UriParam`, `@UriPath` or `@Metadata`, and remove the setter + Javadoc that held the old text. +- Use the official terms of Java and of the library that the component uses, and describe only what the code does. +- The component description is the Javadoc of the endpoint class, the class annotated with `@UriEndpoint`. Write one + sentence that says what the component does, starting with a verb such as Send, Receive or Expose, and name no options. + It appears in one-line places, such as the component list on the website. The build keeps the Javadoc only up to the + first line that ends with a period. +- Change only description text: no option names, default values, labels or types. + +## Regenerating the files + +Build the project once from the root folder with `mvn clean install -Dquickly`. Then run `mvn install -DskipTests` in +these folders, in this order. Do not pass `-Dquickly` here, because it skips the formatter and the DSL generation. + +1. the component module +2. `catalog/camel-catalog` +3. `dsl/camel-endpointdsl` +4. `dsl/camel-componentdsl`, if a component option or the component description changed + +Commit all generated files: the component JSON and its copy in the catalog, the Endpoint DSL and Component DSL classes +and, if the component description changed, the doc page and its copy in the catalog. Review Comment: 📝 **Nit (STE — sentence length):** This sentence runs 35 words across two lines, exceeding the 25-word guideline. Split into two sentences: ```suggestion Commit all generated files in the same commit: the component JSON and its copy in the catalog, the Endpoint DSL and Component DSL classes. If the component description changed, also commit the doc page and its copy in the catalog. ``` -- 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]
