gnodet-bot commented on code in PR #29943: URL: https://github.com/apache/camel/pull/29943#discussion_r4575844246
########## tasks/component-descriptions.md: ########## @@ -0,0 +1,400 @@ +# 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. If + the table conflicts with another pull request, keep both changes. + +## 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. If you find such a problem, for + example a wrong label, report it in the pull request description, so that the reviewers can decide how to fix it. Review Comment: 📝 **Nit (STE — sentence length):** This sentence runs 28 words across two lines, exceeding the 25-word STE limit. Split it into two sentences: ```suggestion - Change only description text: no option names, default values, labels or types. If you find such a problem, report it in the pull request description. The reviewers can then decide how to fix it. ``` -- 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]
