This suggested gained a lot of +1's so i want to talk about it a moment. I don't think it's suitable to *remove* APIs that still exist from the docs or hide them from being enumerable.
There are just too many node programs out there now and people who want to understand existing code need to read the documentation for an API that *is still active* should be able to find and view it and to debug that API via test code in the repl which making non-enumerable makes annoying. This just isn't the grown up way to handle a mistake or a deprecation. We need to call out in the docs that 1) this exists and is still available 2) it should not be used 3) why it should not be used and links to doing things the "right" way. Pretending it doesn't exist when it still does is like pretending we never made this mistake even though it still works in node. Let's take responsibility for this and do what's best for all of the existing and future users of node. -Mikeal On Aug 20, 2012, at August 20, 20128:53 AM, Tim Caswell <[email protected]> wrote: > How about removing it from the docs and making it non-enumerable in > the fs module. Then any new developers won't know it's there unless > they are reading someone else's code. Or maybe in the docs simply say > that it shouldn't be used and is only left there so as to not break > old code. Also, how is this different from deprecation? > > On Sun, Aug 19, 2012 at 4:02 PM, Bert Belder <[email protected]> wrote: >> On Sunday, August 19, 2012 8:23:53 PM UTC+2, Nuno Job wrote: >>> >>>>> Maybe a note in the docs tell people that fs.stat is a better choice? >>> >>> Good idea Mikeal. Deprecation console.error && pointing people to >>> fs.stat in the docs should do the trick. >> >> >> I don't see enough compelling reasons to deprecate it. I think a doc >> addition that warns people about the funky signature and the anti-pattern >> would suffice. >> >> - Bert >> >> >> -- >> Job Board: http://jobs.nodejs.org/ >> Posting guidelines: >> https://github.com/joyent/node/wiki/Mailing-List-Posting-Guidelines >> You received this message because you are subscribed to the Google >> Groups "nodejs" group. >> To post to this group, send email to [email protected] >> To unsubscribe from this group, send email to >> [email protected] >> For more options, visit this group at >> http://groups.google.com/group/nodejs?hl=en?hl=en > > -- > Job Board: http://jobs.nodejs.org/ > Posting guidelines: > https://github.com/joyent/node/wiki/Mailing-List-Posting-Guidelines > You received this message because you are subscribed to the Google > Groups "nodejs" group. > To post to this group, send email to [email protected] > To unsubscribe from this group, send email to > [email protected] > For more options, visit this group at > http://groups.google.com/group/nodejs?hl=en?hl=en -- Job Board: http://jobs.nodejs.org/ Posting guidelines: https://github.com/joyent/node/wiki/Mailing-List-Posting-Guidelines You received this message because you are subscribed to the Google Groups "nodejs" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/nodejs?hl=en?hl=en
