Improve documentation of crypto_knowledge.KeyType
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
diff --git a/scripts/mbedtls_dev/crypto_knowledge.py b/scripts/mbedtls_dev/crypto_knowledge.py
index e9dad1d..fb96ec0 100644
--- a/scripts/mbedtls_dev/crypto_knowledge.py
+++ b/scripts/mbedtls_dev/crypto_knowledge.py
@@ -30,27 +30,40 @@
"""Analyze a key type.
The key type must be specified in PSA syntax. In its simplest form,
- this is a string 'PSA_KEY_TYPE_xxx' which is the name of a PSA key
+ `name` is a string 'PSA_KEY_TYPE_xxx' which is the name of a PSA key
type macro. For key types that take arguments, the arguments can
be passed either through the optional argument `params` or by
passing an expression of the form 'PSA_KEY_TYPE_xxx(param1, param2)'
- as the a string.
+ in `name` as a string.
"""
self.name = name.strip()
+ """The key type macro name (``PSA_KEY_TYPE_xxx``).
+
+ For key types constructed from a macro with arguments, this is the
+ name of the macro, and the arguments are in `self.params`.
+ """
if params is None:
if '(' in self.name:
m = re.match(r'(\w+)\s*\((.*)\)\Z', self.name)
assert m is not None
self.name = m.group(1)
params = ','.split(m.group(2))
- if params is None:
- self.params = params
- else:
- self.params = [param.strip() for param in params]
+ self.params = (None if params is None else
+ [param.strip() for param in params])
+ """The parameters of the key type, if there are any.
+
+ None if the key type is a macro without arguments.
+ """
self.expression = self.name
+ """A C expression whose value is the key type encoding."""
if self.params is not None:
self.expression += '(' + ', '.join(self.params) + ')'
self.private_type = re.sub(r'_PUBLIC_KEY\Z', r'_KEY_PAIR', self.name)
+ """The key type macro name for the corresponding key pair type.
+
+ For everything other than a public key type, this is the same as
+ `self.name`.
+ """
ECC_KEY_SIZES = {
'PSA_ECC_FAMILY_SECP_K1': (192, 224, 256),
