document python crypto apis

docs/api.md

@@ -9,16 +9,28 @@ Syntax used below is a valid Python function declaration with type hints defined
 ``` python
 def trezor.crypto.base58.encode(data: bytes) -> str
 ```
+
+Convert bytes to base58 encoded string.
+
 ``` python
 def trezor.crypto.base58.decode(string: str) -> bytes
 ```
+
+Convert base58 encoded string to bytes.
+
 ``` python
 def trezor.crypto.base58.encode_check(data: bytes) -> str
 ```
+
+Convert bytes to base58 encoded string, append checksum.
+
 ``` python
 def trezor.crypto.base58.decode_check(string: str) -> bytes
 ```
 
+Convert base58 encoded string to bytes and verify checksum.
+
+
 ###trezor.crypto.curve
 
 ####trezor.crypto.curve.ed25519
@@ -200,6 +212,21 @@ Returns the digest of hashed data.
 def trezor.crypto.hmac.new(key, msg, digestmod) -> Hmac
 ```
 
+Creates a HMAC context object.
+
+``` python
+def Hmac.update(self, msg: bytes) -> None
+```
+
+Update the context with data.
+
+``` python
+def Hmac.digest(self) -> bytes
+```
+
+Returns the digest of processed data.
+
+
 ##trezor.msg
 
 ``` python

docs/api.py

@@ -1,10 +1,12 @@
 #!/usr/bin/python3
 import os
+import re
 
 def process_file(fn):
     mod, ext = os.path.splitext(fn)
     src = open('../%s' % (fn)).readlines()
     r = []
+    cls = ''
     if ext in ['.h', '.c']:
         for l in src:
             l = l.rstrip()
@@ -24,6 +26,20 @@ def process_file(fn):
                 r.append('``` python')
                 r.append('def %s.' % mod + l[4:-1])
                 r.append('```')
+            elif l.startswith('### '):
+                r.append(l[4:])
+            elif l.startswith('###'):
+                r.append('')
+            elif l.startswith('class '):
+                cls = re.match('class ([A-Za-z0-9_]*)', l).group(1)
+            elif l.startswith('    def ') and not l.startswith('    def __init__'):
+                r.append('``` python')
+                r.append('def %s.' %  cls + l[8:-1])
+                r.append('```')
+            elif l.startswith('    ### '):
+                r.append(l[8:])
+            elif l.startswith('    ###'):
+                r.append('')
     return r
 
 def main():

src/trezor/crypto/base58.py

@@ -19,6 +19,9 @@ from .hashlib import sha256
 _alphabet = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'
 
 def encode(data: bytes) -> str:
+###
+### Convert bytes to base58 encoded string.
+###
     origlen = len(data)
     data = data.lstrip(b'\0')
     newlen = len(data)
@@ -37,6 +40,9 @@ def encode(data: bytes) -> str:
 
 
 def decode(string: str) -> bytes:
+###
+### Convert base58 encoded string to bytes.
+###
     origlen = len(string)
     string = string.lstrip(_alphabet[0])
     newlen = len(string)
@@ -55,11 +61,16 @@ def decode(string: str) -> bytes:
 
 
 def encode_check(data: bytes) -> str:
+###
+### Convert bytes to base58 encoded string, append checksum.
+###
     digest = sha256(sha256(data).digest()).digest()
     return encode(data + digest[:4])
 
-
 def decode_check(string: str) -> bytes:
+###
+### Convert base58 encoded string to bytes and verify checksum.
+###
     result = decode(string)
     result, check = result[:-4], result[-4:]
     digest = sha256(sha256(result).digest()).digest()

src/trezor/crypto/hmac.py

@@ -1,3 +1,9 @@
+def new(key, msg, digestmod) -> Hmac:
+###
+### Creates a HMAC context object.
+###
+    return Hmac(key, msg, digestmod)
+
 class Hmac:
     def __init__(self, key, msg, digestmod):
         self.__digestmod = digestmod
@@ -12,13 +18,18 @@ class Hmac:
             self.update(msg)
 
     def update(self, msg: bytes) -> None:
+    ###
+    ### Update the context with data.
+    ###
         self.__inner.update(msg)
 
     def digest(self) -> bytes:
+    ###
+    ### Returns the digest of processed data.
+    ###
         outer = self.__digestmod()
         outer.update(bytes((x ^ 0x5C) for x in self.__key))
         outer.update(self.__inner.digest())
         return outer.digest()
 
-def new(key, msg, digestmod) -> Hmac:
-    return Hmac(key, msg, digestmod)
+