Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
doc: add example for cipher.update() #28373
Not disagreeing with any of the facts stated but for the record: Documentation changes are a poor choice for code + learn tasks and we should avoid them in the future. They are easy to do poorly, often difficult to do in a way that materially improves the docs, attract way more comments and (often contradictory) suggestions than simple code changes, and require skills that many code + learn attendees may not have.
That's an aside, though. Now back to reviewing this specific change...
@sergiovillagran - your interest in collaborating on Node.js development is really appreciated, this isn't at all about the quality of your work! Its unfortunate that you were asked to make this change, only to find out later that there is disagreement about whether its an improvement.
With respect to the change itself, I agree with @mscdex that the docs become harder to use when we copy the cipher examples from the cipher class section header into each individual cipher method. IMHO, this decreases the quality of our docs.
tniessen left a comment
Thank you for your contribution, and sorry for chiming in late. So this is mostly a copy of a previous example, the only addition seems to be this:
// If data is a Buffer, then inputEncoding is ignored. let buff = Buffer.from('some clear text data', 'utf8') let encryptedBuffer = cipher.update(buff, null, 'hex') console.log(encryptedBuffer) // Prints: 2bb302c9618b22e9f843afc1befd7997 // If no outputEncoding is provided, a Buffer is returned. let buffer = cipher.update('some clear text data', 'utf8') console.log(buffer) // Prints <Buffer 42 6a 2e 23 bd 8d 51 c7 16 cf 47 f6 9f 16 b6 b6>
First, the snippet should probably use
It might also be confusing to beginners that the example is calling
The code snippet appears as if it was meant to be a complete example, but it's missing the important call to
It doesn’t seem like there’s anything new for the TSC to discuss at this point, and it doesn’t look like this PR is currently moving forward either, so I’ll remove the tsc-agenda label.
Anybody can feel free to re-add it, though. In particular, the @nodejs/tsc has not really discussed the underlying question here of whether we’re generally okay with mostly duplicated examples.