Hacker News Reader

Comment by coldpie | Hacker News Reader

> it's not that they're going to finally fully document the Win32 API (their online documentation is quite often inaccurate)

Okay, this is tangential to your point, and I'm no fan of Microsoft's, but I really have to defend MSDN here. MSDN is by a wide margin the best and most complete API documentation I've ever seen. Yes, it's wrong sometimes, but that's because it fucking exists. Almost every function, and certainly every function a typical developer is going to care about, is documented. Even crazy obscure shit like wmvcore COM interfaces[1]. You don't even know what that is, but look at all that fucking documentation! Oh my god. My life would be so much harder as a Wine developer if it weren't for MSDN. Every win32 API developer at Microsoft deserves a gold fucking star for actually writing documentation. They certainly don't deserve chastisement for not being perfect.

[1] https://msdn.microsoft.com/en-us/library/windows/desktop/dd7...

View on HN

The developers at the Wine project have mentioned multiple times in various places how sketchy and inaccurate MSDN is.

Maybe MS has tried to clean that up recently, but it has a track record of inaccuracy, at best.

I wouldn't be surprised if the Wine developers were the ones submitting the corrections to the MSDN, anyway.

Sure, it'd be cool if everything was perfect. Then we wouldn't need to write all these tests

    $ cat src/wine/*/*/tests/*.c | wc -l
    1085766

But we don't live in that world and it's far more interesting to compare like with like. When you take into account its scope, in terms of completeness and usefulness, MSDN is head and shoulders above every other API doc I can think of except maybe Java, which is also excellent. Certainly better than Apple, and don't even get me started on most open source APIs.

Yes, MSDN documentation may be inaccurate from the perspective of people trying to REPLICATE THE ACTUAL IMPLEMENTATION of the APIs!

That's not the purpose of MSDN documentation though.

That's my point. I want that you publish what your API actually does. I've written programs which MSDN said wouldn't work. Clearly a bug in MSDN. Did MS not know? Or is it to trip up wine?

Either way, its clear vendor lockin

You may not understand something important about Windows API. Let me explain.

There's the documented, public functionality that Windows implements and wants all the applications to adhere to. This should be documented and it is.

Then there's the functionality that Microsoft had to implement behind the scenes because some important application used it in an incorrect way or it worked by accident. They didn't want that application to break with a new release of Windows. Now Microsoft doesn't want new applications to use this, so they don't document it. I think that is absolutely correct.

MSDN API documentation is meant for people that write applications the way Microsoft wants the applications written.

Wine isn't an application. They want to emulate what Windows does. The API documentation is not for that purpose and it shouldn't be.

That being said, there are APIs in Windows that are secret and undocumented. Those should not be used by applications. Windows isn't open source. Accept it.

MSDN really is pretty damn extensive, but I'd say the documentation for the Java ecosystem is considerably better. Especially the JavaDoc for the standard library.

MSDN is a piece of shit.

The documentation is shallow, it does not even consistently describe all the parameters of everything. It's often wrong, it does not carry any information about bugs and lacks an easily reachable diff for older versions.

Yes, it has a page for everything. It's just that most of the pages are useless.

It used to be the best thing around, but it's not the 90's anymore. Almost all mainstream development platforms out there have better documentation than MS. (And it does not help that almost all of them also have saner APIs.)

Reply on news.ycombinator.com