The clincher in my decision to ditch JSDoc, however, came when I realized that, for most projects, I won’t want the documentation in the same file as the code. While I generally prefer that they be in the same file, I will often have 4-10 times more documentation than actual code, and the bandwidth overhead seems unnecessary. JavaDoc and JSDoc of course require that any documentation be in the same files, since that’s where they parse method signatures and such.
So I think I’ll follow Chris Dolan’s advice from my original post and fall back on Good ‘ole POD. POD allows me to write as much or as little documentation as I like, with methods and functions documented in an order that makes sense to me, with headings even! I can write long descriptions, synopses, and even documentation completely unrelated to specifics of the interface. And all in a separate file, even!
Looking for the comments? Try the old layout.