Add header file docs for openssl/core_numbers.h and openssl/core_names.h #11963
Conversation
|
As a side note related to this pr: looking at the content of openssl/include/openssl/core_numbers.h Lines 90 to 128 in e847085 Also, there are parts in the header where the IDs are intertwined with the function declarations, and other parts where the IDs precede the declarations blockwise. openssl/include/openssl/core_numbers.h Lines 130 to 150 in e847085 I find the latter variant more readable. Whichever variant you choose, it should be consistent. |
|
I don’t know why I received this it looks like it belongs to someone else
and it happened because of the github iOS app it looks like a security
issue to me there are enumerated blobs and shit in here . This is me
saying report this error . I don’t know if this were someone else besides
me if it would be a big deal or not but it looks like a personal email I’m
not sure.
…On Tue, May 26, 2020 at 5:56 PM Matthias St. Pierre < ***@***.***> wrote:
As a side note related to this pr: looking at the content of
<openssl/core_numbers.h> I wonder whether the header name
<openssl/core_functions.h> wouldn't be more appropriate? It's all about
defining provider *functions* and the *number*, (i.e. the function ID) is
just a part of their definition.
https://github.com/openssl/openssl/blob/e847085914476636d75ee1874b78e1c0e983da6e/include/openssl/core_numbers.h#L90-L128
Also, there are parts in the header where the IDs are intertwined with the
function declarations, and other parts where the IDs precede the
declarations blockwise.
https://github.com/openssl/openssl/blob/e847085914476636d75ee1874b78e1c0e983da6e/include/openssl/core_numbers.h#L130-L150
I find the latter variant more readable. Whichever variant you choose, it
should be consistent.
—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
<#11963 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AMU3DNPDR6X6CVJ53L6TPMLRTRCKDANCNFSM4NKIM5PQ>
.
|
|
Sure thing just wanted to make sure it wasn’t something serious
…On Tue, May 26, 2020 at 6:20 PM Matthias St. Pierre < ***@***.***> wrote:
@Tymbur <https://github.com/Tymbur> I have no idea why you received the
mail. It was a regular post of mine on pull request #11963
<#11963>. To prevent further email
notifications, you can follow the link to the pull request and unsubscribe
from the thread.
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
<#11963 (comment)>,
or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AMU3DNPJPP45QD5KYZXEGMLRTRFFBANCNFSM4NKIM5PQ>
.
|
Not sure that's the best replacement names either, the name "core_functions" would make me expect to see a number of declarations for functions offered by the core of libcrypto... regarding the name "core_numbers", I would argue that these are dispatch numbers offered by the core, along with the function types that the provider need to associate with those numbers. |
I would say that it depends. The functions offered by the core (!!!) is a looong list, that's a lot of jumping back and forth to see what function number macro corresponds to what function signature. |
|
Now that I've commented on stuff that isn't about this PR itself at all, anyone want to review? |
|
There are some make doc-nits errors in travis. |
|
Assuming tests all pass. |
A CAVEATS section is present in this manual. That section name is
borrowed from OpenBSD, where mdoc(7) explains it like this:
CAVEATS
Common misuses and misunderstandings should be explained in this
section.
|
Care to re-approve with the squash commit I just added? |
|
Reapproved |
|
I dislike adding a new CAVEATS section. OpenSSL has always used NOTES, which seems quite appropriate here. Don't blaze new trails. Be boring. Be consistent. |
|
You often want to collapse NOTES into DESCRIPTION too... I think this particular one does deserve a bit more "voice" than a mere note... |
|
Yes, I often collapse NOTES into DESCRIPTION because it doesn't deserve a separate call-out, and folks get lazy by just adding NOTES after the main manpage is written. Look at other notes sections. This is no different. I'm sure I'll lose this point, sigh, but you're still wrong. |
|
24 hours has passed since 'approval: done' was set, but as this PR has been updated in that time the label 'approval: ready to merge' is not being automatically set. Please review the updates and set the label manually. |
Reviewed-by: Shane Lontis <shane.lontis@oracle.com> (Merged from #11963)
A CAVEATS section is present in this manual. That section name is
borrowed from OpenBSD, where mdoc(7) explains it like this:
CAVEATS
Common misuses and misunderstandings should be explained in this
section.
Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
(Merged from #11963)
No description provided.