my dog learned polymorphism*
The moose likes Beginning Java and the fly likes How to use Java Docs when writing a program? Big Moose Saloon
  Search | Java FAQ | Recent Topics | Flagged Topics | Hot Topics | Zero Replies
Register / Login


Win a copy of Java 8 in Action this week in the Java 8 forum!
JavaRanch » Java Forums » Java » Beginning Java
Bookmark "How to use Java Docs when writing a program?" Watch "How to use Java Docs when writing a program?" New topic
Author

How to use Java Docs when writing a program?

Jj Taylor
Greenhorn

Joined: Jan 20, 2013
Posts: 19
Hi there, I've been learning Java pretty hard over the last few months and I'm finding it difficult to understand the docs, this might be a stupid question and hard to understand...

Lets say your are writing a system tic tac toe game using the Swing libs how would I use the Java Doc reference with it?

Would anyone be so kind to give me an example how they work with references, lets say your stuck on something and you go in the docs, how would you work with it?

Any advice would be great..

Thanks
Junilu Lacar
Bartender

Joined: Feb 26, 2001
Posts: 4419
    
    5

The JavaDocs are most helpful when you already know a little bit about what it is you're looking for. For example, if you knew about the String class but weren't quite sure how the format() method worked, you'd go to the JavaDocs to find out more. When you are less clear on what you're looking for, it's more or less a hit or miss, hunt and click proposition. A good Google search term (e.g. "java swing event listener javadoc") might help narrow it down for you but that's about the best you may be able to do.


Junilu - [How to Ask Questions] [How to Answer Questions]
Winston Gutkowski
Bartender

Joined: Mar 17, 2011
Posts: 7081
    
  16

Jj Taylor wrote:Would anyone be so kind to give me an example how they work with references, lets say your stuck on something and you go in the docs, how would you work with it?

As Junilu said, the javdocs (sometimes called the API docs) are a reference - they tell you what a class can do, but not necessarily how to use it.
java.util.Calendar is a classic case in point - despite the fact that it has fairly extensive documentation, it really doesn't explain how you should use it (which is why we get a lot of questions about it). For that, you should generally look at the tutorials - although unfortunately, in the case of Calendar, there's precious little, even there (there are several Calendar tutorials on the 'Net though).

As for Swing, there are whole books written about it, so it would probably be overkill to try to put all of that in the API docs. There is quite an extensive section in the tutorials though.

One tip with the API docs: What you can do is to pull up the docs for a Swing class - eg, JFrame and press the 'Package' button at the top of the screen, which will take you to the Swing package docs. From there, clicking on the 'Description' link will give you some more general information about the package. This works for any class that is part of a specific package but, as Junilu said, how good the docs are is a bit of a lottery.

Winston

Isn't it funny how there's always time and money enough to do it WRONG?
Artlicles by Winston can be found here
Jj Taylor
Greenhorn

Joined: Jan 20, 2013
Posts: 19
Thanks for the advice/reply to my first post..

Could you give me an small and easy project idea I could work on so I can get the hang of it using the docs? When I've got used to using them I reckon I could have broader Ideas myself...

Thanks
Campbell Ritchie
Sheriff

Joined: Oct 13, 2005
Posts: 36599
    
  16
You should probably start writing documentation on a class you wrote as a beginner.
There are guidelines about documentation comments here, and in Joshu Bloch’s Effective Java™ (2nd edition).
Jj Taylor
Greenhorn

Joined: Jan 20, 2013
Posts: 19
Useful info thanks
Jj Taylor
Greenhorn

Joined: Jan 20, 2013
Posts: 19
From Campbell Ritchie comment which seems like a 'Must Do' for beginners starting out = defiantly writing out comments and keeping your project files safe and available for future reference (I guess everyone has there own stlye of writing and will pick what they need up easier)

Lets say, I wanted to work on a Tic Tac Toe style game and of course you'd write out the plan, What would be the first steps obviously you would need to reference the docs/API... I'm not asking for a whole source file, just some basic concepts...
Paul Clapham
Bartender

Joined: Oct 14, 2005
Posts: 18168
    
    8

I'm confused about what you are asking. To use the Java API documentation for a class (let's say JTable) there are two steps: (1) open the page for JTable in your browser (2) look for the information you want. Notice that the process doesn't have much to do with the code you're writing, except that presumably it uses JTable and you have a question about some method.

So what are you asking? Are you asking how to find that page? Are you asking what you should want to find?
Campbell Ritchie
Sheriff

Joined: Oct 13, 2005
Posts: 36599
    
  16
I didn’t mean to sound like a “must do”, but writing documentation comments is one of the skills a Java Developer needs. What I meant was, take a class you have already written and are familiar with, and add documentation to that.
Jj Taylor
Greenhorn

Joined: Jan 20, 2013
Posts: 19
Campbell Ritchie, my reply was ment to come out like you had a good point for future reference for searches (I couldnt find the actual answer I was looking for on google)

Paul Clapham, I'll probably have to go over the beginners tutorials then on methods, classes, functions so I can understand the documents more so they appeal to me, I've only been studying 3 months solid, maybe I'll need to take in more of what they mean before starting a project for a portfolio made for sending jobs

I've been fustrated the first 2 months but taking in more of the language and its starting to settle in and becoming exciting, its just I keep going on the basics then when it comes to viewing the docs it 75% of time goes over my head and dont understand...

Stuff like simple outputting to the console i.e System.out.println("Hello World") but what else could I do with the System.out Doc to maybe change colours of text or even other stuff? Just simple little things like that... Being able to learn from the docs on simple stuff then I could maybe be able to learn more on the todays GUI Docs like swing... etc
Paul Clapham
Bartender

Joined: Oct 14, 2005
Posts: 18168
    
    8

Jj Taylor wrote:Stuff like simple outputting to the console i.e System.out.println("Hello World") but what else could I do with the System.out Doc to maybe change colours of text or even other stuff?


The documentation is just that -- it tells you how the thing being documented works. That's all it is. You can't do anything with it except read it.

Now if you were asking how to write text to the console in colours and so on, that's a perfectly reasonable question and one that's been asked quite a few times before.

(I should mention that it's extremely frustrating when you're looking through something's documentation for a feature that the something doesn't support. It takes quite a while before you realize that it wasn't just you looking for things which you couldn't find, it was that the things really weren't there. And it isn't the purpose of documentation to provide a long list of features that the something doesn't support.)
Jj Taylor
Greenhorn

Joined: Jan 20, 2013
Posts: 19
Thats great, I'm finding it easier to understand.. I've just knocked up a bit of simple code and how would I go about using JavaDocs to find a way where if the user enters any other other than an integer it will repeat, I take it there will be looping involved, but how would I find the method to read up on it... I'm guessing there'll be some sort of importing other classes involved with a method that deals with it. This should hopefully be my last question on this subject.....

Paul Clapham
Bartender

Joined: Oct 14, 2005
Posts: 18168
    
    8

Well, you wouldn't. The Javadocs are not where you would look if you have no idea what classes to use. They are more like for "What does method X actually do?" There's over 5,000 standard Java classes so you have no hope of browsing through them in the hope of finding what you want. Think of them as like the dictionary -- if you want to know what "aglet" means, then look in the dictionary. But if you want to know the name of the little plastic thing on the end of a shoelace, then don't bother scanning through the dictionary until you find it.

You're better off reading the tutorials to learn about Java. Maybe you've already seen them, but here's a link to the home page: The Java Tutorials. There's a ton of tutorials you could go through, but start with the basics.
Jj Taylor
Greenhorn

Joined: Jan 20, 2013
Posts: 19
Thanks, I'll be spending more time on the basics... So far with the docs I've been learning basic String Methods and messing around with them, i.length() and its becoming easier for me to how it works, here is a demo from learning the string length method and storing it as a variable



Just a quick one though and a bit off subject - I've been trying to loop this program for the last hour, with FOR and DO WHILE but I've not been succesful (even from some google searches) - How would I repeat this program so it goes back to "Please enter any word under 15 letters" if its over 15...

Thanks overall for your help
Campbell Ritchie
Sheriff

Joined: Oct 13, 2005
Posts: 36599
    
  16
[Tangent]Why are you using else if in that last bit of code when plain else would do the trick?[/Tangent]
Campbell Ritchie
Sheriff

Joined: Oct 13, 2005
Posts: 36599
    
  16
[Tangent2]Do you realise you have an out‑by‑one error in that code, too?[/Tangent2]
Winston Gutkowski
Bartender

Joined: Mar 17, 2011
Posts: 7081
    
  16

Jj Taylor wrote:Just a quick one though and a bit off subject - I've been trying to loop this program for the last hour, with FOR and DO WHILE but I've not been succesful (even from some google searches) - How would I repeat this program so it goes back to "Please enter any word under 15 letters" if its over 15...

My suggestion: show us what you've tried, and maybe we can point you in the right direction. Far better for you to work it out for yourself than for us to simply hand you a piece of code.

And BTW, I think you're doing just fine: keep it up. Programming is definitely something that is best learnt by doing - even if it's a bit frustrating at times.
And I'm afraid it doesn't get any better either; just that the things that frustrate you get more complex. Back in the days of 40lb monitors we used to call it "terminal stripe" - ie, the stripe you get on your forehead from banging your head against it.

You young 'uns have it easy these days with these soft flat screens.

Winston
Jj Taylor
Greenhorn

Joined: Jan 20, 2013
Posts: 19
Campbell, Its just a bit of code I've been messing about with - not the next minecraft. And I've tried it without the if and get errors....

Gutkowski, funny stuff! and good point on trying to learn it myself even if it is fustrating, I've wrote down tips since I've been learning as well as other peoples and they say frustration can hold you back a lot. Thats something I'm trying to keep in mind, if I get fustrated I'll give it up for a few days but I suppose if your in a job thats on demand its different. Another one is as a beginner always remember that other peoples codes are different when working on the same project for example. Good for confidence knowing these. I'm finding it hard to find a project to work on but some inspiration will come up eventually and need to make sure its something I'm not gunna get bored with
Campbell Ritchie
Sheriff

Joined: Oct 13, 2005
Posts: 36599
    
  16
Jj Taylor wrote:Campbell, Its just a bit of code I've been messing about with . . .
Which means it is much easier to get right. You only have twelve lines with anything written on. It is so much easier to find your errors. And it is so much easier to get into the habit of doing things right now, rather than when you are faced with 5000 lines to write. There are all sorts of improvements I can suggest…


…and will! Whether you want them or not
What happens when you pass a 15‑letter String, eg "abcdefghijklmno"? That is what I meant about out‑by‑one. Out‑by‑one errors are very common, and you need to get used to looking for them.
I could see no difference in behaviour when I put // after else and moved the { to the next line. What errors were you experiencing?
The names Systemin outstring and x are not helpful; the first two give the impression that they mean something different from what you mean them to mean. And x (which is not a good name for an int; i j k l are better for an int) doesn’t tell you anything about what it is supposed to mean.
You have some iffy indenting; never use tabs, and your longest line is 110 keystrokes on my editor, probably 126 on yours, which is too long. You can break it esily like this:You also have too many blank lines; you can delete lines 2 5 6 8 9 11 17 25 and 27, and actually make the code easier to read.
Jj Taylor
Greenhorn

Joined: Jan 20, 2013
Posts: 19
Jj wrote: Thanks, I'll be spending more time on the basics... So far with the docs I've been learning basic String Methods and 'messing' around with them, i.length() and its becoming easier for me to how it works, here is a 'demo' from learning the 'string length method' and storing it as a variable

I didnt know there were any rules to learning and giving out examples of what I've learnt from peoples advice? If i were to work for a company or a serious personal project then obviously the code would be neater.. Thanks for the 'tab' tip but I dont understand what you mean about my variables are badly named? nearly every tutorial and peoples code I've come across has x, y, xx, xxx, yyy, y or whatever, messing around and coming up with some name quick like "Systemin" meaning, to me, I'm going do some kind of input. Same with 'outstring', named quickly from the back of my head so I know what it means. Like I say, if I were to a plan/design for a personal project I would most likely have better names for my variables...

Now, as for the whitespaces, personally I read this better whilst learning - everyones different and if I knew I was going to save this for future reference I would make something neat of it as well as // comments

Finally, the else instead else if worked yes but only after taking (outstring < x) which you didnt make clear. It wasnt actually there when I started it because I was 'playing' around with the IF THEN WHILE CATCH loops and was going to add another System.out.println in there.

Sorry if my punctuation's bad, you might 'wanna' comment on that too....
Campbell Ritchie
Sheriff

Joined: Oct 13, 2005
Posts: 36599
    
  16
Oh, so that was the error. I obviously wasn’t clear when I told you about removing the if. Sorry.
As for x y z, such variable names are possible when you have a tiny application. But if you come back in a few weeks, can you remember what they mean? Can you tell from reading “outstring” that it actually means the length of the String supplied? If not, then stringLength would be better. You can use inputText.length() directly in the expression, if you prefer.
 
I agree. Here's the link: http://aspose.com/file-tools
 
subject: How to use Java Docs when writing a program?
 
Similar Threads
FileNotFoundException
General java job questions
Java 1b
Passed SCJP 6 with 91%!
Study Material for Formatting and Parsing