docs: "Crypto Cipher" API isn't available in the docs

[pfalcon]

So, we have https://github.com/zephyrproject-rtos/zephyr/blob/master/include/crypto/cipher.h#L9 which clearly has docstrings defining a whole API subsystem. However, search for "Crypto Cipher APIs" (section title from that file) doesn't give useful hits: https://docs.zephyrproject.org/latest/search.html?q=Crypto+Cipher+APIs&check_keywords=yes&area=default

It looks like that API is not included in the docs. That might be as well because of warning sign in that file:

• [Experimental] Users should note that the APIs can change

• as a part of ongoing development.

But that notice is from 2016. By 2020, it may be still experimental, but not as experimental as to exclude it from the docs.

@dbkinder, Can you please do initial triaging on this, maybe you're aware of the situation, maybe there's just some markup error. Then as needed, let's involve Anas et al.

[pfalcon]

Note that we have https://docs.zephyrproject.org/latest/guides/crypto/index.html . But that goes just orthogonal: So, Zephyt has own crypto API, in particular, it provides wrappers for 3rd-party libraries, like mbedTLS. Wrappers, because we want to use people to use native Zephyr API, which may be implemented by different underlying crupto providers. And yet we have that "Cryptography" section where only thing that it does is exposes 3rd-party lib directly.

Also cc: @d3zd3z to be aware of this situation.

[pfalcon]

Actually, looking closer at cipher.h, the majority of comments there are simple comments /* */, and not docstring comments /** */. @dbkinder, is that what precludes a useful doc section to be generated out of it?

[pfalcon]

David let me know that he no longer oversees Zephyr docs. So, ping to you, @nashif, whether you know of a reason why Crypto API docs shouldn't be in the manual. If not, I'll try to look into getting them rendered there.

[nashif]

Actually, looking closer at cipher.h, the majority of comments there are simple comments /* */, and not docstring comments /** */. @dbkinder, is that what precludes a useful doc section to be generated out of it?

This is correct, need **, but also need to put this in some group to make it easy to import them into rst, so first goal is to get them listed here:

https://docs.zephyrproject.org/apidoc/latest/modules.html

@pfalcon you already started fixing that, so it would be great if you can continue... reassigning.

[pfalcon]

@pfalcon you already started fixing that, so it would be great if you can continue...

Sounds good, in my list.

[nashif]

taking a stab on this now