Java-Gaming.org Hi !
Featured games (83)
games approved by the League of Dukes
Games in Showcase (523)
Games in Android Showcase (127)
games submitted by our members
Games in WIP (592)
games currently in development
News: Read the Java Gaming Resources, or peek at the official Java tutorials
 
    Home     Help   Search   Login   Register   
Pages: [1]
  ignore  |  Print  
  MSDN versus JavaDocs  (Read 3103 times)
0 Members and 1 Guest are viewing this topic.
Offline barfy

Junior Devvie




The evidence of things not seen


« Posted 2004-12-11 09:19:53 »

Hi guys,

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 Sad.

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.
Offline William Denniss

JGO Coder


Projects: 2


Fire at will


« Reply #1 - Posted 2004-12-11 12:35:49 »

Quote
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.

Will.

Offline aldacron

Senior Devvie


Medals: 9
Exp: 16 years


Java games rock!


« Reply #2 - Posted 2004-12-13 09:45:12 »

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?
Games published by our own members! Check 'em out!
Legends of Yore - The Casual Retro Roguelike
Offline barfy

Junior Devvie




The evidence of things not seen


« Reply #3 - Posted 2004-12-13 12:30:10 »

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 :

1  
2  
3  
4  
5  
6  
reference operator[](
   size_type _Pos
);
const_reference operator[](
   size_type _Pos
) const;


Doing a search for the type "reference" would produce this:

1  
2  
3  
4  
A type that provides a reference to an element in a sequence controlled by the associated container.

Remarks
The type describes a reference to an element of the sequence controlled by the associated container.


and this:

1  
typedef typename Container::reference reference;


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.
Offline blahblahblahh

JGO Coder


Medals: 1


http://t-machine.org


« Reply #4 - Posted 2004-12-13 16:48:51 »

Quote
Personally I don't see a problem with MSDN.


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 Smiley.

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 Wink

malloc will be first against the wall when the revolution comes...
Offline aldacron

Senior Devvie


Medals: 9
Exp: 16 years


Java games rock!


« Reply #5 - Posted 2004-12-13 23:52:36 »

Quote


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.
Offline aldacron

Senior Devvie


Medals: 9
Exp: 16 years


Java games rock!


« Reply #6 - Posted 2004-12-14 00:10:21 »

Quote

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.
Offline barfy

Junior Devvie




The evidence of things not seen


« Reply #7 - Posted 2004-12-14 03:44:11 »

I w

Quote

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.
Offline blahblahblahh

JGO Coder


Medals: 1


http://t-machine.org


« Reply #8 - Posted 2004-12-14 08:02:29 »

Quote

It would be great to see an HTMLHelp version of the Java docs.


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 Sad.

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).

EDIT: does java 5 now: http://javadocs.planetmirror.com/javadoce.html

malloc will be first against the wall when the revolution comes...
Offline aldacron

Senior Devvie


Medals: 9
Exp: 16 years


Java games rock!


« Reply #9 - Posted 2004-12-14 16:16:18 »

Quote


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:

Here.
Games published by our own members! Check 'em out!
Legends of Yore - The Casual Retro Roguelike
Offline jbanes

JGO Coder


Projects: 1


"Java Games? Incredible! Mr. Incredible, that is!"


« Reply #10 - Posted 2004-12-14 16:29:47 »

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.

But...

If you're into WinHelp, then might I suggest WinHelp for Linux? Alternatively, you can always convert to JavaHelp.

Java Game Console Project
Last Journal Entry: 12/17/04
Offline blahblahblahh

JGO Coder


Medals: 1


http://t-machine.org


« Reply #11 - Posted 2004-12-14 18:45:55 »

Quote
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.

malloc will be first against the wall when the revolution comes...
Offline princec

« JGO Spiffy Duke »


Medals: 422
Projects: 3
Exp: 16 years


Eh? Who? What? ... Me?


« Reply #12 - Posted 2004-12-14 19:42:55 »

Sounds like a case for a miniature servlet type engine to me.

Cas Smiley

Offline jbanes

JGO Coder


Projects: 1


"Java Games? Incredible! Mr. Incredible, that is!"


« Reply #13 - Posted 2004-12-14 19:56:23 »

Quote
Sounds like a case for a miniature servlet type engine to me.

Cas Smiley


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.

Java Game Console Project
Last Journal Entry: 12/17/04
Offline aldacron

Senior Devvie


Medals: 9
Exp: 16 years


Java games rock!


« Reply #14 - Posted 2004-12-15 05:32:48 »

Quote
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.

But...

If you're into WinHelp, then might I suggest WinHelp for Linux? Alternatively, you can always convert to JavaHelp.


WinHelp is the nasty, ewww. But we were talking about HTMLHelp, which is nice Smiley 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 Smiley
Pages: [1]
  ignore  |  Print  
 
 
You cannot reply to this message, because it is very, very old.

 

Add your game by posting it in the WIP section,
or publish it in Showcase.

The first screenshot will be displayed as a thumbnail.

SHC (24 views)
2014-11-25 12:00:59

SHC (23 views)
2014-11-25 11:53:45

Norakomi (19 views)
2014-11-25 11:26:43

Gibbo3771 (22 views)
2014-11-24 19:59:16

trollwarrior1 (36 views)
2014-11-22 12:13:56

xFryIx (74 views)
2014-11-13 12:34:49

digdugdiggy (52 views)
2014-11-12 21:11:50

digdugdiggy (46 views)
2014-11-12 21:10:15

digdugdiggy (41 views)
2014-11-12 21:09:33

kovacsa (68 views)
2014-11-07 19:57:14
Understanding relations between setOrigin, setScale and setPosition in libGdx
by mbabuskov
2014-10-09 22:35:00

Definite guide to supporting multiple device resolutions on Android (2014)
by mbabuskov
2014-10-02 22:36:02

List of Learning Resources
by Longor1996
2014-08-16 10:40:00

List of Learning Resources
by SilverTiger
2014-08-05 19:33:27

Resources for WIP games
by CogWheelz
2014-08-01 16:20:17

Resources for WIP games
by CogWheelz
2014-08-01 16:19:50

List of Learning Resources
by SilverTiger
2014-07-31 16:29:50

List of Learning Resources
by SilverTiger
2014-07-31 16:26:06
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
Powered by MySQL Powered by PHP Powered by SMF 1.1.18 | SMF © 2013, Simple Machines | Managed by Enhanced Four Valid XHTML 1.0! Valid CSS!