Update docs

[lovesh]

Some of the code samples in the Readme are obsolete. Also, some new features aren't documented in Readme. See this and this.

[ineiti]

From your comment in #35, we have the following points we can do easily:

• [ ] But some of the code examples are out of date so they need to be fixed by looking at the tests I mentioned before.
• [ ] Secondly there are some new features added like more protocols for range proofs which you can see in these tests but missing in the Readme.
• [ ] The API described in the Readme is low-level and a higher level abstraction exists and is documented here conceptually but lacks code examples which could be written referring these tests, mostly this one. If you haven't seen this abstraction, I'll suggest taking a look. Its more ergonomic than the code examples in the main Readme.

Regarding the BBS/BBS+ threshold part, we did not use that and wouldn't know how to correctly document it.

For your last point, where you ask us what would help us, I think the following would be great, what do you think? We would be happy to take on that part, too, after we finished with the above points.

1. Add an automatic API documentation generation like typedoc
2. Write the corresponding API documentation for the anonymous credentials
3. Re-write the README by distributing the current documentation throughout the code tree and making sure that the typedoc (or whatever we'll use) integrates these texts as well

[lovesh]

Hi @ineiti . I can do 2. Regarding 3, you mean splitting the README at the repo root to multiple READMEs at different sub-directories?

making sure that the typedoc (or whatever we'll use) integrates these texts as well

Can you please give an example of this?

[lanterno]

Hey @lovesh, I actually discussed this with Linus, so I can respond since he seems busy..

Both 2. and 3. assume using a CLI tool that generates API interface documentation from the code rather than writing it manually.

This morning, I was looking at https://typedoc.org/ (for the first time), and it generated a documentation just like this https://typedoc.org/example/ but with a less good UI.

What I know so far is that typedoc can import a readme file automatically, but I don't know if it can import multiple markdown files from different locations in the repo.

I'm attaching a screenshot of how using typedoc looks like on my machine now:

I think it can be easily hosted on github pages.

[lanterno]

On a related topic, I'm starting on the first point you mentioned before

But some of the code examples are out of date so they need to be fixed by looking at the tests I mentioned before.

and I wanted to check if this type of change would be good (for example).

Basically, the current examples use the schema from the tests, but since it doesn't work outside the tests, the examples were broken. Now the question is, should all the examples now follow one specific signature scheme (BBS/BBS+/PS/..) or how do you like it to look?

[lovesh]

Hi @lanterno

What I know so far is that typedoc can import a readme file automatically, but I don't know if it can import multiple markdown files from different locations in the repo.

What i understood from Linus's comment was the opposite, i.e. typedoc will somehow take the code comments (say on top of a function) and render that in a readme. Found this plugin that can generate markdown from typedoc. But either way, yes, we can host the generated docs on github.

but with a less good UI.

There are themes and plugins that can help.

and I wanted to check if this type of change would be good (for example).

Yes.

Now the question is, should all the examples now follow one specific signature scheme (BBS/BBS+/PS/..) or how do you like it to look?

Yes, we should pick one scheme say BBS+ and put a note on top saying that other schemes can be used similarly and link to the tests to show signature of functions of other schemes.

[lanterno]

What i understood from Linus's comment was the opposite, i.e. typedoc will somehow take the code comments (say on top of a function) and render that in a readme

It does both. It builds a home page from the readme, and then uses the code along with its comments to build a reference API.

Found this plugin that can generate markdown from typedoc There are themes and plugins that can help.

Nice!

Yes, we should pick one scheme say BBS+ and put a note on top saying that other schemes can be used similarly and link to the tests to show signature of functions of other schemes.

Perfect! I can do that! Do you have a preference for one of them? I like the BBS variant because it has shorter names and the differences with BBS+ will be minimal.

[lovesh]

It does both. It builds a home page from the readme, and then uses the code along with its comments to build a reference API.

Nice. Will check more.

I like the BBS variant because it has shorter names and the differences with BBS+ will be minimal.

Yes, BBS is fine.

[ineiti]

What i understood from Linus's comment was the opposite, i.e. typedoc will somehow take the code comments (say on top of a function) and render that in a readme. Found this plugin that can generate markdown from typedoc. But either way, yes, we can host the generated docs on github.

Sorry for the confusion. I actually meant:

• split the main README in different READMEs
• add API documentation
• have a tool which merges all of this into (a) nice html page(s)

Even though creating the READMEs from the code might also be nice. But I think it will get complicated to know what to update...