Missing documentation for some S3 Object methods

[albertogg]

Describe the issue with documentation There are some methods that are missing documentation for their optional parameters. I haven't used all methods in the Aws::S3::Object class so I can't talk for all of them, but for example upload_file only reflects 3 optional parameters multipart_threshold, thread_count, and progress_callback but the reality is that it uses multipart upload code and for that reason it inherits all of the options available in that method too. The same thing happens with the copy_to and copy_from methods.

I hope I made the point clear if not I can elaborate further.

Thanks, Alberto

[mullermp]

Thanks for opening an issue. Yes, resource objects (such as Aws::S3::Object) leverage Client API operation methods (such as multipart upload) and have their own documentation. Client API methods are code generated from the API source. I think we can probably add some YARD references to those operations.

[albertogg]

@mullermp if there's an example you can link me to I can try to tackle this. The other thing will be just to add a reference, some basic wording on the YARD documentation something like "This method shares all options from this other method". I think this will be enough.

[mullermp]

Sure, taking upload_file as an example, I think YARD references for @see and using braces {} would be appropriate, perhaps like

Under @param source:

This method takes additional options for {Client#put_object} when file sizes below the multipart threshold. For files larger than the multipart threshold, options for {Client#create_multipart_upload}, {Client#complete_multipart_upload}, and {Client#upload_part} can be provided.

At the very bottom:

@see Client#put_object
@see Client#create_multipart_upload
@see Client#complete_multipart_upload
@see Client#upload_part

To be thorough (if you're up for it), this kind of pattern should be done for all methods in aws-sdk-s3/customizations/.

[github-actions[bot]]

⚠️COMMENT VISIBILITY WARNING⚠️

Comments on closed issues are hard for our team to see. If you need more assistance, please either tag a team member or open a new issue that references this one. If you wish to keep having a conversation with other community members under this issue feel free to do so.