[PATCH] D108525: Fix documentation and snippets for the handle attributes.

[Aaron Ballman via Phabricator via cfe-commits]

aaron.ballman closed this revision.
aaron.ballman added a comment.

In D108525#2960903 , @paulherman 
wrote:

> In D108525#2960877 , @aaron.ballman 
> wrote:
>
>> In D108525#2960765 , @paulherman 
>> wrote:
>>
>>> Thanks for the very prompt review! I'm afraid I no longer have permissions 
>>> to submit --my last commit was in 2015 and I recall that I had SVN access, 
>>> but many things have changed. Would it be possible to submit this on my 
>>> behalf?
>>
>> I'm happy to commit on your behalf -- what name and email address would you 
>> like me to use for patch attribution?
>
> Thanks a lot! You can use "Paul Herman" as name and paulher...@google.com as 
> email.

Thanks! I've commit on your behalf in f71706046144bd49af397fbed10fbe130433b969 
.


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D108525/new/

https://reviews.llvm.org/D108525

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D108525: Fix documentation and snippets for the handle attributes.

[Paul Herman via Phabricator via cfe-commits]

paulherman added a comment.

In D108525#2960877 , @aaron.ballman 
wrote:

> In D108525#2960765 , @paulherman 
> wrote:
>
>> Thanks for the very prompt review! I'm afraid I no longer have permissions 
>> to submit --my last commit was in 2015 and I recall that I had SVN access, 
>> but many things have changed. Would it be possible to submit this on my 
>> behalf?
>
> I'm happy to commit on your behalf -- what name and email address would you 
> like me to use for patch attribution?

Thanks a lot! You can use "Paul Herman" as name and paulher...@google.com as 
email.


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D108525/new/

https://reviews.llvm.org/D108525

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D108525: Fix documentation and snippets for the handle attributes.

[Aaron Ballman via Phabricator via cfe-commits]

aaron.ballman added a comment.

In D108525#2960765 , @paulherman 
wrote:

> Thanks for the very prompt review! I'm afraid I no longer have permissions to 
> submit --my last commit was in 2015 and I recall that I had SVN access, but 
> many things have changed. Would it be possible to submit this on my behalf?

I'm happy to commit on your behalf -- what name and email address would you 
like me to use for patch attribution?


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D108525/new/

https://reviews.llvm.org/D108525

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D108525: Fix documentation and snippets for the handle attributes.

[Paul Herman via Phabricator via cfe-commits]

paulherman added a comment.

Thanks for the very prompt review! I'm afraid I no longer have permissions to 
submit --my last commit was in 2015 and I recall that I had SVN access, but 
many things have changed. Would it be possible to submit this on my behalf?


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D108525/new/

https://reviews.llvm.org/D108525

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D108525: Fix documentation and snippets for the handle attributes.

[Aaron Ballman via Phabricator via cfe-commits]

aaron.ballman accepted this revision.
aaron.ballman added a comment.
This revision is now accepted and ready to land.

LGTM, thank you!


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D108525/new/

https://reviews.llvm.org/D108525

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D108525: Fix documentation and snippets for the handle attributes.

[Paul Herman via Phabricator via cfe-commits]

paulherman updated this revision to Diff 368127.
paulherman added a comment.

Explaining the tag argument.


Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D108525/new/

https://reviews.llvm.org/D108525

Files:
  clang/include/clang/Basic/AttrDocs.td


Index: clang/include/clang/Basic/AttrDocs.td
===
--- clang/include/clang/Basic/AttrDocs.td
+++ clang/include/clang/Basic/AttrDocs.td
@@ -5881,19 +5881,21 @@
 If this annotation is on a function or a function type it is assumed to return
 a new handle. In case this annotation is on an output parameter,
 the function is assumed to fill the corresponding argument with a new
-handle.
+handle. The attribute requires a string literal argument which used to
+identify the handle with later uses of ``use_handle`` or
+``release_handle``.
 
 .. code-block:: c++
 
   // Output arguments from Zircon.
   zx_status_t zx_socket_create(uint32_t options,
-   zx_handle_t __attribute__((acquire_handle)) * 
out0,
-   zx_handle_t* out1 [[clang::acquire_handle]]);
+   zx_handle_t 
__attribute__((acquire_handle("zircon"))) * out0,
+   zx_handle_t* out1 
[[clang::acquire_handle("zircon")]]);
 
 
   // Returned handle.
-  [[clang::acquire_handle]] int open(const char *path, int oflag, ... );
-  int open(const char *path, int oflag, ... ) __attribute__((acquire_handle));
+  [[clang::acquire_handle("tag")]] int open(const char *path, int oflag, ... );
+  int open(const char *path, int oflag, ... ) 
__attribute__((acquire_handle("tag")));
   }];
 }
 
@@ -5901,12 +5903,13 @@
   let Category = HandleDocs;
   let Content = [{
 A function taking a handle by value might close the handle. If a function
-parameter is annotated with ``use_handle`` it is assumed to not to change
+parameter is annotated with ``use_handle(tag)`` it is assumed to not to change
 the state of the handle. It is also assumed to require an open handle to work 
with.
+The attribute requires a string literal argument to identify the handle being 
used.
 
 .. code-block:: c++
 
-  zx_status_t zx_port_wait(zx_handle_t handle [[clang::use_handle]],
+  zx_status_t zx_port_wait(zx_handle_t handle [[clang::use_handle("zircon")]],
zx_time_t deadline,
zx_port_packet_t* packet);
   }];
@@ -5915,12 +5918,13 @@
 def ReleaseHandleDocs : Documentation {
   let Category = HandleDocs;
   let Content = [{
-If a function parameter is annotated with ``release_handle`` it is assumed to
-close the handle. It is also assumed to require an open handle to work with.
+If a function parameter is annotated with ``release_handle(tag)`` it is 
assumed to
+close the handle. It is also assumed to require an open handle to work with. 
The
+attribute requires a string literal argument to identify the handle being 
released.
 
 .. code-block:: c++
 
-  zx_status_t zx_handle_close(zx_handle_t handle [[clang::release_handle]]);
+  zx_status_t zx_handle_close(zx_handle_t handle 
[[clang::release_handle("tag")]]);
   }];
 }
 


Index: clang/include/clang/Basic/AttrDocs.td
===
--- clang/include/clang/Basic/AttrDocs.td
+++ clang/include/clang/Basic/AttrDocs.td
@@ -5881,19 +5881,21 @@
 If this annotation is on a function or a function type it is assumed to return
 a new handle. In case this annotation is on an output parameter,
 the function is assumed to fill the corresponding argument with a new
-handle.
+handle. The attribute requires a string literal argument which used to
+identify the handle with later uses of ``use_handle`` or
+``release_handle``.
 
 .. code-block:: c++
 
   // Output arguments from Zircon.
   zx_status_t zx_socket_create(uint32_t options,
-   zx_handle_t __attribute__((acquire_handle)) * out0,
-   zx_handle_t* out1 [[clang::acquire_handle]]);
+   zx_handle_t __attribute__((acquire_handle("zircon"))) * out0,
+   zx_handle_t* out1 [[clang::acquire_handle("zircon")]]);
 
 
   // Returned handle.
-  [[clang::acquire_handle]] int open(const char *path, int oflag, ... );
-  int open(const char *path, int oflag, ... ) __attribute__((acquire_handle));
+  [[clang::acquire_handle("tag")]] int open(const char *path, int oflag, ... );
+  int open(const char *path, int oflag, ... ) __attribute__((acquire_handle("tag")));
   }];
 }
 
@@ -5901,12 +5903,13 @@
   let Category = HandleDocs;
   let Content = [{
 A function taking a handle by value might close the handle. If a function
-parameter is annotated with ``use_handle`` it is assumed to not to change
+parameter is annotated with ``use_handle(tag)`` it is assumed to not to change
 the state of the handle. It is also assumed to require an open handle to 

[PATCH] D108525: Fix documentation and snippets for the handle attributes.

[Aaron Ballman via Phabricator via cfe-commits]

aaron.ballman added a comment.

Thank you for fixing up the docs! As long as we're here, I suggested some extra 
documentation wording to make it clear what the argument is and why it's used.




Comment at: clang/include/clang/Basic/AttrDocs.td:5884
 the function is assumed to fill the corresponding argument with a new
 handle.
 





Comment at: clang/include/clang/Basic/AttrDocs.td:5905
+parameter is annotated with ``use_handle(tag)`` it is assumed to not to change
 the state of the handle. It is also assumed to require an open handle to work 
with.
 





Comment at: clang/include/clang/Basic/AttrDocs.td:5919
+If a function parameter is annotated with ``release_handle(tag)`` it is 
assumed to
 close the handle. It is also assumed to require an open handle to work with.
 




Repository:
  rG LLVM Github Monorepo

CHANGES SINCE LAST ACTION
  https://reviews.llvm.org/D108525/new/

https://reviews.llvm.org/D108525

___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

[PATCH] D108525: Fix documentation and snippets for the handle attributes.

[Paul Herman via Phabricator via cfe-commits]

paulherman created this revision.
Herald added a reviewer: aaron.ballman.
paulherman requested review of this revision.
Herald added a project: clang.
Herald added a subscriber: cfe-commits.

Repository:
  rG LLVM Github Monorepo

https://reviews.llvm.org/D108525

Files:
  clang/include/clang/Basic/AttrDocs.td


Index: clang/include/clang/Basic/AttrDocs.td
===
--- clang/include/clang/Basic/AttrDocs.td
+++ clang/include/clang/Basic/AttrDocs.td
@@ -5887,13 +5887,13 @@
 
   // Output arguments from Zircon.
   zx_status_t zx_socket_create(uint32_t options,
-   zx_handle_t __attribute__((acquire_handle)) * 
out0,
-   zx_handle_t* out1 [[clang::acquire_handle]]);
+   zx_handle_t 
__attribute__((acquire_handle("zircon"))) * out0,
+   zx_handle_t* out1 
[[clang::acquire_handle("zircon")]]);
 
 
   // Returned handle.
-  [[clang::acquire_handle]] int open(const char *path, int oflag, ... );
-  int open(const char *path, int oflag, ... ) __attribute__((acquire_handle));
+  [[clang::acquire_handle("tag")]] int open(const char *path, int oflag, ... );
+  int open(const char *path, int oflag, ... ) 
__attribute__((acquire_handle("tag")));
   }];
 }
 
@@ -5901,12 +5901,12 @@
   let Category = HandleDocs;
   let Content = [{
 A function taking a handle by value might close the handle. If a function
-parameter is annotated with ``use_handle`` it is assumed to not to change
+parameter is annotated with ``use_handle(tag)`` it is assumed to not to change
 the state of the handle. It is also assumed to require an open handle to work 
with.
 
 .. code-block:: c++
 
-  zx_status_t zx_port_wait(zx_handle_t handle [[clang::use_handle]],
+  zx_status_t zx_port_wait(zx_handle_t handle [[clang::use_handle("zircon")]],
zx_time_t deadline,
zx_port_packet_t* packet);
   }];
@@ -5915,12 +5915,12 @@
 def ReleaseHandleDocs : Documentation {
   let Category = HandleDocs;
   let Content = [{
-If a function parameter is annotated with ``release_handle`` it is assumed to
+If a function parameter is annotated with ``release_handle(tag)`` it is 
assumed to
 close the handle. It is also assumed to require an open handle to work with.
 
 .. code-block:: c++
 
-  zx_status_t zx_handle_close(zx_handle_t handle [[clang::release_handle]]);
+  zx_status_t zx_handle_close(zx_handle_t handle 
[[clang::release_handle("tag")]]);
   }];
 }
 


Index: clang/include/clang/Basic/AttrDocs.td
===
--- clang/include/clang/Basic/AttrDocs.td
+++ clang/include/clang/Basic/AttrDocs.td
@@ -5887,13 +5887,13 @@
 
   // Output arguments from Zircon.
   zx_status_t zx_socket_create(uint32_t options,
-   zx_handle_t __attribute__((acquire_handle)) * out0,
-   zx_handle_t* out1 [[clang::acquire_handle]]);
+   zx_handle_t __attribute__((acquire_handle("zircon"))) * out0,
+   zx_handle_t* out1 [[clang::acquire_handle("zircon")]]);
 
 
   // Returned handle.
-  [[clang::acquire_handle]] int open(const char *path, int oflag, ... );
-  int open(const char *path, int oflag, ... ) __attribute__((acquire_handle));
+  [[clang::acquire_handle("tag")]] int open(const char *path, int oflag, ... );
+  int open(const char *path, int oflag, ... ) __attribute__((acquire_handle("tag")));
   }];
 }
 
@@ -5901,12 +5901,12 @@
   let Category = HandleDocs;
   let Content = [{
 A function taking a handle by value might close the handle. If a function
-parameter is annotated with ``use_handle`` it is assumed to not to change
+parameter is annotated with ``use_handle(tag)`` it is assumed to not to change
 the state of the handle. It is also assumed to require an open handle to work with.
 
 .. code-block:: c++
 
-  zx_status_t zx_port_wait(zx_handle_t handle [[clang::use_handle]],
+  zx_status_t zx_port_wait(zx_handle_t handle [[clang::use_handle("zircon")]],
zx_time_t deadline,
zx_port_packet_t* packet);
   }];
@@ -5915,12 +5915,12 @@
 def ReleaseHandleDocs : Documentation {
   let Category = HandleDocs;
   let Content = [{
-If a function parameter is annotated with ``release_handle`` it is assumed to
+If a function parameter is annotated with ``release_handle(tag)`` it is assumed to
 close the handle. It is also assumed to require an open handle to work with.
 
 .. code-block:: c++
 
-  zx_status_t zx_handle_close(zx_handle_t handle [[clang::release_handle]]);
+  zx_status_t zx_handle_close(zx_handle_t handle [[clang::release_handle("tag")]]);
   }];
 }
 
___
cfe-commits mailing list
cfe-commits@lists.llvm.org
https://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits