Conversation
|
A very rough draft only. Refer #9011 |
Add documentation to indicate the interaction between global (context level) property queries and local (passed to fetch) ones.
a0bcb20 to
fd1c979
Compare
|
Merged, thanks @levitte (after a rebase and squash) |
Add documentation to indicate the interaction between global (context level) property queries and local (passed to fetch) ones. Reviewed-by: Richard Levitte <levitte@openssl.org> (Merged from #9042)
|
This seems to have caused |
| The full syntax for property queries appears below, but the available syntatic | ||
| features are: | ||
|
|
||
| =over |
mspncp
left a comment
There was a problem hiding this comment.
Sorry for being late to the game, but since the nit's need to be fixed anyway, you might as well take a look at my review comments.
| A context based property query that applies to all fetch operations and a local | ||
| property query. | ||
| Where both the context and local queries include a clause with the same name, | ||
| the local clause is used and the context one ignored. |
There was a problem hiding this comment.
I'd suggest to change this sentence to
Where both the context and local queries include a clause with the same name,
the local clause overrides the context clause.
| the local clause is used and the context one ignored. | ||
| For example, a context property query of "fips=yes" and a local property query | ||
| of "fips=no" would result in algorithms that have the "fips" property set t | ||
| "no". |
There was a problem hiding this comment.
and to omit this sentence, because it does not really add anything to the previous.
(If you prefer to keep the sentence, then a typo needs to be fixed: set t "no" - set to "no")
| =head2 Override | ||
|
|
||
| It is possible for a local property query to override a clause in the context | ||
| property query by preceeding the property name with a '-'. |
There was a problem hiding this comment.
I would not call this an override, it's more like erasing/removing the context clause.
Also, using the - prefix does not seem very intuitive to me. The -fips clause could easily be misinterpreted as "disable fips" instead of "I don't care about fips". How about adding a new special keyword instead, something like fips=any, fips=dontcare or fips=undef?
There was a problem hiding this comment.
I've changed it to remove.
I'm less sure about the fips=xxx suggestion. There is another prefix operator but no predefined values that do special things. Removing one prefix operator and putting a special value in its place seems to complicated things.
|
|
||
| It is possible for a local property query to override a clause in the context | ||
| property query by preceeding the property name with a '-'. | ||
| For example, a conxtet property query that contains "fips=yes" would normally |
| result in implementations that have "fips=yes". | ||
| However, if the setting of | ||
| the "fips" property is irrelevant to the operations being performed, the local | ||
| property query can include the clause "-fips". |
There was a problem hiding this comment.
fips=irrelevant would be a nice way to say it, too ;-)
| property query can include the clause "-fips". | ||
| Note that the local property query could not use "fips=no" because that would | ||
| disallow any implementations with "fips=yes" rather than not caring about the | ||
| setting. |
There was a problem hiding this comment.
TL;DR: All the explanations could probably be shortened, if the - prefix would be replaced by a meaningful special keyword, see above.
Add documentation to indicate the interaction between global (context level)
property queries and local (passed to fetch) ones.