Docs!

[mikeal]

We need more docs.

The new CID and Block interface aren’t documented at all.

[rvagg]

Labelling this as exp/beginner good first issue and help wanted because it would be great for someone with fresh eyes to help tackle this. We have docs in the README, they're not terrible, but it'd be great to expand them and explain some things a bit more. An examples directory would be awesome too to show off what it can do, just some basic things like what's reflected in the README that users can run.

This library is key to our JS stack, so making sure it has great entry docs is important.

[MF416]

@rvagg - currently part of the bootcamp and was looking to take this on as a first "bug fix" project. Is anyone else working on this / is this still open?

[rvagg]

In speaking to @MF416 elsewhere, my suggestion is something like:

• Focus on examples to start with - the README is currently mostly a series of short examples
• We have https://github.com/ipld/js-examples but it's a big example that goes beyond what we need here, but might be useful in learning the basic pattern
• Make an examples/ directory, try and build small example executables based on the README's snippets with some console.log() output
• Revisit README as you go to see how each of those sections could be improved based on the example experience.

The https://github.com/ipld/js-car repo is another place where I've spent quite a bit of time trying to use examples as documentation. Those are all runnable on the commandline, and are even run as part of CI to make sure they continue to work.

Of course, when you get further experience with the patterns here, you might see obvious ways to do pure documentation work in the README as well.

Two other bootcampers are going to help get some basic docs onto ipld.io for JS and they'll be pointing to this repo as the main source of documentation for JS IPLD, so improving things here will be great timing.

[AuHau]

Ehm I agree that more docs is needed. Tbh I am super confused, lost and unsure how to navigate and place this library. I am coming here from https://github.com/multiformats/js-multicodec repo looking for similar functionality that I can't find at all.

For example, where I can get a list of all codecs? Translating from codec names to codec values? Prefixing/getting prefix? Tbh. I can't find pretty much anything from the js-multicodec functionality here.

[rvagg]

@achingbrain what do you think about keeping js-multicodec alive, in a trimmed-down form, to just ship the table with simple accessors for the data? While we certainly don't want to encourage its general use, I've found use for it when I want access to the table and don't care about its size in my dependency tree. We could address that problem with documentation. I hadn't noticed the deprecation notice on there until now.

@AuHau to your question - you should consider whether you need access to the whole table. Part of the big shift we've done lately is to decouple all of these pieces so that you only have to consume the minimal pieces you need for your application. The multicodec table is getting quite large and there's not usually a good reason to have the whole thing in your application, usually you just want information about a couple of codecs and hashers and having the whole table is far too big (and it's always growing). All our new codecs and hashers ship with both their code and name on their main exports.

[AuHau]

@rvagg that makes sense. For my use-case, I don't need the whole table so I will adapt to your new approach. But I would advise documenting this "big shift" into places where people come from to this repo (like the js-multicodec, js-cid etc.).

[rvagg]

@AuHau yep, point taken, and this is the right issue to make such a comment! Our docs need more expansion.

[achingbrain]

I think having the old module still in use makes the intended style of use less clear so probably best to avoid it?

Maybe you or @Gozala or someone else who came up with the idea could write a blog post about the thought process behind the change with lots of examples and an upgrade guide?

[Gozala]

I think having the old module still in use makes the intended style of use less clear so probably best to avoid it?

I think general functionality of tagging bytes with a code and an ability to match by tag is worth having somewhere (which would correspond to addPrefix / rmPrefix), although that place is probably not js-multicodec. I am assuming most mulitformat values use same prefixing logic, if that is not the case please let me know.

Maybe you or @Gozala or someone else who came up with the idea could write a blog post about the thought process behind the change with lots of examples and an upgrade guide?

I did advocate for passing around codecs as opposed their codes and would not mind drafting a rational for it if someone is willing to review so we can post it to a blog or at least add .md file here that other repos can point to.