paul-rogers commented on issue #2047: DRILL-7675: Work around for partitions sender memory use URL: https://github.com/apache/drill/pull/2047#issuecomment-609455569 @arina-ielchiieva, thanks for the review. How do you recommend we modify the documentation? My thought was this: I put a one-line summary in the option description. Details on how the option works are in the file where the option is used. My thought was that the detailed user description should go into the docs somewhere. We should decide how we want to handle option documentation. Most require more background explanation than fits in a simple doc string. (For this one, we have to explain how the partition sender works in order to know why you even need the option.) To me, the docs seem the place for these explanations. This leaves the doc string as a reminder and summary. An improvement might be: 1. Put the doc strings in a resource file. 2. Add a link to the docs where we provide the full description. Checking the docs, I didn't immediately find a reference section for the options, so looks like that is an opportunity for improvement. We'd want two entries for each option: 1. A theory-of-operation section that explains the background along with relevant SQL commands, start-up options and system/session options. 2. A tabular reference section that contains a link to the theory of operation section and the relevant details (default value, one-line doc string, etc.) By having the option descriptions in a resource file, we could generate the reference section above. All of these are beyond the scope of this PR, however.
---------------------------------------------------------------- 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. For queries about this service, please contact Infrastructure at: [email protected] With regards, Apache Git Services
