docknetwork / crypto-wasm-ts

Typescript abstractions over Rust crypto library's WASM wrapper
Apache License 2.0
28 stars 9 forks source link

Update docs #36

Open lovesh opened 4 weeks ago

lovesh commented 4 weeks ago

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

ineiti commented 3 weeks ago

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

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 commented 3 weeks ago

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 commented 2 weeks ago

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: Screenshot 2024-11-05 at 14 54 39

I think it can be easily hosted on github pages.

lanterno commented 2 weeks ago

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 commented 2 weeks ago

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 commented 2 weeks ago

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 commented 2 weeks ago

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 commented 2 weeks ago

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:

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

lovesh commented 1 week ago

@lanterno @ineiti PR for points 1 and 2. For 2, most significant changes are in this Readme.

lovesh commented 1 day ago

@lanterno @ineiti typedoc has been integrated in github workflow and docs are deployed here.

EDIT: But the links to code from the rendered Readme at https://docknetwork.github.io/crypto-wasm-ts/ are broken because those URLs are now relative to docknetwork.github.io.