docs: update block api documentation

[hacdias]

Closes #3913.

I have some inline notes and questions.

[hacdias]

https://github.com/ipfs/js-ipfs/blob/master/packages/ipfs-core-types/src/block/index.ts does not include this option. However, the go-ipfs CLI seems to support this option and found this mentions in this repository:

js-ipfs/packages/ipfs-cli/src/commands/block/put.js

Lines 34 to 37 in 548cfb2

	mhlen: {
	describe: 'multihash hash length',
	default: undefined
	},

js-ipfs/packages/ipfs-http-server/src/api/resources/block.js

Line 111 in 548cfb2

mhlen: Joi.number(),

• Is this option relevant? Should it be removed?
• Is it supported by js-ipfs or only go-ipfs?

[achingbrain]

It's not supported by js-ipfs and I'm not clear on what it even does for go-ipfs. It defaults to -1 which means.. 🤷

If you could find out the what and the why maybe we could even remove it entirely.

[hacdias]

Well, it seems to be literally the multihash length, but doesn't seem to be very useful looking at the very limited search results. I tried figuring out if this was useful when opening this PR, but couldn't find anything that explained why it may be needed.

[lidel]

I had to refactor relevant go-ipfs code around this recently and can provide some details.

afaik the only place where this is used, is when mhlen gets passed deep into go-multihash code responsible for digert (Sum) calculation: https://github.com/multiformats/go-multihash/blob/75ae3688857d036ea15947be9df68d3172b19470/sum.go

tldr:

• -1 is the implicit default which means "set length based on hashing function output"
  • same applies to any value <=0
• setting custom mhlen allows for truncating longer digests produces by alternative hash functions
• setting it to longer than the default output of specific hash function will produce error

[achingbrain]

LGTM, have responded inline to the queries, we can merge once they are resolved.