documenting APIs for weakly-typed languages?

[cellio]

I've been building and documenting application programming interfaces (APIs) for years, using tools like Javadoc to generate the reference documentation from the code and special comments in the code. I've got a pretty good handle on this in general -- but so far I've always worked in languages with stronger typing, like Java and C++, ones where the parameters and return values can be specific classes, or things like List<String> (rather than just a list), and so on. But now I need to do it for Javascript, where all the code will tell you is that that parameter is, say, an object -- not what specific properties that object needs to have and what their types are, for example. Our API is going to have a lot of that type of parameter. So now I'm wondering what's considered best practices for documenting those -- obviously the documentation from the comments has to address it, but I can imagine a few different ways of doing it and haven't found useful examples in the wild yet. (That doesn't mean they're not there, of course.)

I asked a question about this on Writers.StackExchange, hoping to tap the wisdom of the net. But I figure some of my readers might be able to offer suggestions. If you comment here you'll help me, but if you instead comment or answer there you'll help the broader internet. (Also, I'd like to see more technical-writing content there, for which there's a chicken-and-egg problem.) Either way, I'd welcome input, tips, warnings, horror stories... whatever you've got.

We haven't chosen a tool yet; we've found half a dozen for Javascript that we'll be looking at. So if I know what's considered the best way to do this I can factor that into the decision, instead of finding myself limited by what the tool we ended up with can support.

Comments

[eub.livejournal.com]

About the problem statement: is the situation that 1) developers want to maintain some kind of function doc comments that include type information, but 2) what kind to use is up in the air?

Unfortunately all I have experience with to do this for JS is Closure type annotations, which you are unlikely to want to use unless you buy into the Closure compiler. They do have some cute features as a type system.

I have noticed in passing that Python has a gaggle of different solutions to this problem, using various markup languages, some javadoc-ish, some markdown-ish. I've never lined these all up to see how they compare. StackOverflow has some questions (http://stackoverflow.com/questions/487184/how-do-i-specify-input-and-output-data-types-in-python-comments) in the Python domain.

[metahacker.livejournal.com]

What about a parallel question on Programmers? While less on-topic I bet the pool of answerers with relevant experience would be larger...

Let me think about it, too...interesting conundrum. My first response was "people document JavaScript code??!?" :P

[siderea]

I have no idea what BestPractices are. Myself, I just stick a monster block of comment at the head of either the file or the relevant bit of code, explaining "Okay, here is how I envision this being used, here are the ways this thing will react when passed things with the following properties/attributes/shapes/quantities, etc."

At least, I aspire to doing that. :)