My recent forays into C/C++ and Win32 programming have inevitably led me into the relatively painful task of digging for info on MSDN. In general, coding in C++ is just as much fun as coding in java for me at least. However, documentation wise, compared to the clarity of the javadocs on Sun's website, MSDN is a like a giant steaming pile of ****.

Seems like I've been really spoiled by Java .

Btw, anyone know of a good VS plugin that has a robust C++ syntax parser to highlight spelling errors, missing semicolons or identifiers etc? Something nearly as robust as the one used in IntelliJ's IDE would be good perhaps.

documentation-wise, compared to the clarity of the javadocs on Sun's website, MSDN is a like a giant, steaming pile of ****.

I couldn't agree more. Simple HTML is all I need, no fancy bandwidth sucking graphics and javascript (sorry, VB Script). The F1 help files are even worse. The javadocs are not only clear, but (almost?) everything is documented.

Ever used GTK? Those docs are nice looking, but very thin. You'd think such a popular API would have better docs. *shugs*. This is just one more reason why we are using java I guess.

Personally I don't see a problem with MSDN. The search and index tabs make finding what you are looking for easy, the functions are explained in adequate detail, the examples are illustrative enough, and the dependencies are listed so you know which headers to include and libraries to link with. I find the JavaDocs of the core API lacking at times. We've all read blah's laments about the lack of NIO documentation. Both have their weknesses and strengths, but both serve the purpose well enough.

Throw in the MSDN Knowledge Base and it's the better, IMO. It would be really nice if Sun distributed something like that with the core API docs. I have a multitude of links to articles and tutorials throughout Sun's site (among other sources) covering topics ranging from weak references to new 1.5 features. Why aren't they colocated into a Java Knowledge Base?

One of the reasons behind my dislike for MSDN is the lack of documention defining most of the data types used in the C++ (ms standard) library. There is only so much info you can glean from MSDN before having to dig into the library header files or other references to get a clearer understanding.

Let me give you an example, the operator[] definition for the std::vector class :

So exactly what a "reference" type's expected functionality is and it's purpose is still quite unclear although we know that a "reference" type is simply a typedef of a template typename within a type Container. (Searching for a Container type brings up a similar issue)

IMHO, the java API docs are extremely well organized compared to MSDN. Class explanations are detailed and are available for every single class I've come across so far. Not much need to poke around the source files at all.

It might be a language issue since C/C++ is a lot more complex and therefore harder to describe than Java. But still I think it's really obvious that the style and explanations offered by the java API docs are orders of magnitude clearer than MSDN's.

Well: it's slow, it's got very unclear navigation, and it doesn't display properly if you have large fonts (most of the navbar text vanisehs because MS can't afford to employ just one person who knows how to write HTML).

Quote

Throw in the MSDN Knowledge Base and it's the better, IMO.

The KB is very good. You can spend hours surfing through them, starting with one problem, and finding the solutions/workarounds/explanations to 30 others that had been bothering you for the last few years but you never really thought to try fixing .

By comparison, Sun won't even *let* you look through their nearest equivalent without you telling them your home address, phone number, etc and then logging in. ******* to that...and the search engine on the bug reports is crap, and there's very little (read: nothing) in the way of KB-style short informational documents hyperlinked to "other useful articles on this topic" detailing useful things.

For instance, if MS owned java, you can bet there'd be a KB article on "how to write a NIO server", with links to "how many selectors can you have before performance suffers", etc.

Quote

We've all read blah's laments about the lack of NIO documentation.

LOL, yeah. Maybe one day a JVM staffer will read them and take pity on me

Well: it's slow, it's got very unclear navigation, and it doesn't display properly if you have large fonts (most of the navbar text vanisehs because MS can't afford to employ just one person who knows how to write HTML).

If we're talking about the online version, yeah I'll give you that. It has a crappy search engine also. But the local HTMLHelp version is really nice and easy to use. It would be great to see an HTMLHelp version of the Java docs.

It might be a language issue since C/C++ is a lot more complex and therefore harder to describe than Java. But still I think it's really obvious that the style and explanations offered by the java API docs are orders of magnitude clearer than MSDN's.

The thing about MSDN is that when you are looking for documentation on MS technologies (Win32 API, WinSock, Visual Basic, DirectX), it's an excellent resource. There's no better resource on the Win32 API that I know of. But if you are using it for technologies that were developed elsewere (C/C++, OpenGL), you will find it lacking. There are much better STL references out there, and unless you are using MS-specific extensions there's no reason to use MSDN for that. Java used to be documented in MSDN (not sure if it still is), but would you use that?

Something I do really like about the core Java API docs is that the whole package is relatively small and it's free to download and install locally. MSDN takes up over a gigabyte if you install it locally and requires a (not-so-cheap) subscription in the first place (except for the initial copy that comes with Visual Studio). I can't work without a local copy of the JavaDocs.

There are much better STL references out there, and unless you are using MS-specific extensions there's no reason to use MSDN for that.

I think having other references available isn't the issue here. Shouldn't MS be supporting their product, in this context VC++ and thus the core library also, with proper documentation or at least provide links to some?

Just awhile back, I was looking into the implementation of the not-yet-standard hash_map classes and it wasn't immediately obvious which implementation VC++ was supporting because of the lack of documentation.

But perhaps we are talking about different things. I was (kinda) lamenting the fact that the MSDN docs for the VC++ library should use a similar style to Sun's Javadocs.

On a somewhat related note, the last time I referenced the KB regarding ODBC, I wasn't extremely impressed. It's Mozilla unfriendly and I had to spend quite some time sifting aside the fluff to get (and to an extent infer) the information that I needed.

It's been around for the last 7 years. Sun used to link to it directly from the java.sun.com site with the download for the J2SE docs. I used to download it every version, up until 1.3 IIRC.

In the end, I started using linux too much and so couldn't use the winhelp any more .

From long personal experience, I agree that the winhelp version is MUCH more convenient than the browser version, especially when Mozilla and friends chug at virtual memory/swap/etc when loading the default starting pages for the API (huge).

Aha, I had no idea. Unfortunately, the link isn't working for me. But Google helped me, and following from the Sun site I found the site where I think you got that link from. The other download link they offer works for me:

Personally, I rather despise the WinHelp design. Information is not organized in any way, it's just sort of thrown in there. The result is that you can easily spend hours trying to track down whatever tiny bit of information is critical to your code. The VBA docs in particular, are extremely bad.

Personally, I rather despise the WinHelp design. Information is not organized in any way,

Sure, winhelp sucks.

But...take the JDK docs and put them in winhelp and you get the full standard structure PLUS fast full-indexed text search all in one handy single file (well...in the end they started distributing it as one file per major package IIRC, so you ended up with 10-20 files).

Major problemo with web browers and saved HTML docs: no text-indexing capability.

Macromedia actually uses a Java Applet combined with LiveScript to produce a DHTML interface. The sidebar index is completely dynamic, and all the search data comes form the applet. Surprisingly, it actually works pretty well, even for downloaded documentation.

Apparently the component is part of some framework called "WebWorks". You can see it in action here. (Thanks Google!) Still, I myself am pretty happy with plain, old, HTML JavaDocs.

Personally, I rather despise the WinHelp design. Information is not organized in any way, it's just sort of thrown in there. The result is that you can easily spend hours trying to track down whatever tiny bit of information is critical to your code. The VBA docs in particular, are extremely bad.

WinHelp is the nasty, ewww. But we were talking about HTMLHelp, which is nice If you download the HTLMHelp version of the Javadocs, you get the docs in the same format as you would in your browser (framed), with the addition of the extra panel on the left for the ToC, Index, and Search tabs. It's quite convenient, for example, when browsing the Javadocs for a class to be able to glance over at the ToC to see if there is any other documentation on the particular API to which the class belongs. Then it's a simple matter of clicking it to get there. With standard html docs, you either have to go back throught the history to the main page and find what you want from there or open it up in another tab and look for it. Too much work

java-gaming.org is not responsible for the content posted by its members, including references to external websites,
and other references that may or may not have a relation with our primarily
gaming and game production oriented community.
inquiries and complaints can be sent via email to the info‑account of the
company managing the website of java‑gaming.org