Clarify deprecation comments for RawRequest* functions (hashicorp#20497)

api/client.go

@@ -1280,8 +1280,9 @@ func (c *Client) NewRequest(method, requestPath string) *Request {
 // a Vault server not configured with this client. This is an advanced operation
 // that generally won't need to be called externally.
 //
-// Deprecated: This method should not be used directly. Use higher level
-// methods instead.
+// Deprecated: RawRequest exists for historical compatibility and should not be
+// used directly. Use client.Logical().ReadRaw(...) or higher level methods
+// instead.
 func (c *Client) RawRequest(r *Request) (*Response, error) {
 	return c.RawRequestWithContext(context.Background(), r)
 }
@@ -1290,8 +1291,9 @@ func (c *Client) RawRequest(r *Request) (*Response, error) {
 // a Vault server not configured with this client. This is an advanced operation
 // that generally won't need to be called externally.
 //
-// Deprecated: This method should not be used directly. Use higher level
-// methods instead.
+// Deprecated: RawRequestWithContext exists for historical compatibility and
+// should not be used directly. Use client.Logical().ReadRawWithContext(...)
+// or higher level methods instead.
 func (c *Client) RawRequestWithContext(ctx context.Context, r *Request) (*Response, error) {
 	// Note: we purposefully do not call cancel manually. The reason is
 	// when canceled, the request.Body will EOF when reading due to the way