gnodet-bot commented on code in PR #29943: URL: https://github.com/apache/camel/pull/29943#discussion_r4574440707
########## 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, so that they are clear to people and to AI tools. The same was already done +for the EIPs. + +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 is shown in one-line places, such as the component list on the website. The build keeps the Javadoc only up to the Review Comment: Passive voice: "It is shown in one-line places". Use active voice: ```suggestion It appears in one-line places, such as the component list on the website. The build keeps the Javadoc only up to the ``` ########## 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, so that they are clear to people and to AI tools. The same was already done +for the EIPs. Review Comment: Passive voice ("was already done") and the sentence runs 27+ words across three clauses. Consider splitting: ```suggestion [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 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]
