• Post Reply Bookmark Topic Watch Topic
  • New Topic

Documenting Java APIs  RSS feed

 
Khaled Abolaynain
Greenhorn
Posts: 7
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
I have never been a contributor before, but I just wonder how the process of documenting Java APIs work. It's horrendously horrible and large in volume. What approach do they use when producing new content? Do you use any productivity hacks or word processors? I can't Imagine how human being can write all that stuff! They would need an army. The same thing applies for other programming languages, frameworks, software as well.
 
Carey Brown
Saloon Keeper
Posts: 2439
33
Eclipse IDE Firefox Browser Java MySQL Database VI Editor Windows
  • Likes 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Java API documentation is usually written as specially formatted text comments inserted into the Java code. A tool called javadocs will extract those comments and format them into indexed web pages. And, yes, a person actually had to write all that stuff.
 
Khaled Abolaynain
Greenhorn
Posts: 7
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Carey Brown wrote:Java API documentation is usually written as specially formatted text comments inserted into the Java code. A tool called javadocs will extract those comments and format them into indexed web pages. And, yes, a person actually had to write all that stuff.


Take this for example: https://docs.oracle.com/javase/8/

How many people work on a thing like that? Is there content online on how the full life-cycle of this works? How do you approach this as a developer? Do you get an idea of the whole stuff when learning or search for what you need when you stumble upon a problem when coding?


 
Knute Snortum
Sheriff
Posts: 3438
85
Chrome Eclipse IDE Java Postgres Database VI Editor
  • Likes 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Welcome to the Ranch, Khaled!

You can read about how to write Java comments that become Javadocs here.

The enormous job of documenting a large system of programs becomes a little less daunting when each programmer takes the time to document their own code.
 
Khaled Abolaynain
Greenhorn
Posts: 7
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Knute Snortum wrote:Welcome to the Ranch, Khaled!

You can read about how to write Java comments that become Javadocs here.

The enormous job of documenting a large system of programs becomes a little less daunting when each programmer takes the time to document their own code.


Hi Knute,

Even that link is filled with words. How am I supposed to read something like this?
 
Knute Snortum
Sheriff
Posts: 3438
85
Chrome Eclipse IDE Java Postgres Database VI Editor
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Maybe an example will help:

This will produce the document attached.
JavadocExample.png
[Thumbnail for JavadocExample.png]
Example of Javadoc
 
Khaled Abolaynain
Greenhorn
Posts: 7
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Knute Snortum wrote:Maybe an example will help:. . . .


Now I get it, thank you. Now considering me, the developer. When learning a new language, do I have to know every spec of the language? How do you decide you are ready for your next software project after learning Java? People say practice matters more than reading books and that's true. But when you learn the basics, head to your first project, for example, then stumble upon something you can’t find an answer for. Even if you find the answer, it may not be the optimal. You wouldn’t know the right tool for the job if you didn’t dig up what every tool (language spec) does.
 
Campbell Ritchie
Sheriff
Posts: 53532
126
  • Likes 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Khaled Abolaynain wrote:. . . How many people work on a thing like that? . . .
Don't know. I was told that Oracle had hundreds of people working to develop this, but when they have finished one person will write the documentation.

You sh‍ould be developing software as soon as you start learning, but I don't believe you will do well trying to learn programming from a book. You shou‍ld ask questions of people more experienced than yourself, to avoid suboptimal code. You sho‍uld also put documentation comments into your code from the start (I know many people don't use such comments, but that is the ideal, so you learn documentation as you learn programming). You start with small applications, so as not to run before you walk.
You may find the Java™ Tutorials much easier to understand than the API documentation.

Welcome to the Ranch again

Don't quote the whole of the preceding post; that simply makes the thread longer and longer. I shall remove most of the quote.
 
Jesper de Jong
Java Cowboy
Sheriff
Posts: 15813
76
Android IntelliJ IDE Java Scala Spring
  • Likes 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Don't forget that Java is already 20 years old, so many, many people working at Sun and Oracle have had plenty of time to invent and document the standard Java API - and more is added to it in every new release.

Javadoc is a wonderful invention and fortunately it has been there since the beginning of Java in the 1990's. I don't know if Javadoc was the first with this idea to document an API in the source code the way it does, but it certainly has inspired tools for other languages such as Doxygen, which is similar to Javadoc but for C++ (and other languages).

Khaled Abolaynain wrote:When learning a new language, do I have to know every spec of the language? How do you decide you are ready for your next software project after learning Java? People say practice matters more than reading books and that's true. But when you learn the basics, head to your first project, for example, then stumble upon something you can’t find an answer for. Even if you find the answer, it may not be the optimal. You wouldn’t know the right tool for the job if you didn’t dig up what every tool (language spec) does.

It's just like when you learn a human language, like English. Nobody learns all the words in the dictionary, likewise you don't need to learn the whole language specification by heart. And you get better by practicing, and using it. Don't worry about not finding the optimal solution at first. When writing a program, there are almost always multiple ways to do the same thing, which are equally good. There's not always only one correct or optimal solution.
 
Khaled Abolaynain
Greenhorn
Posts: 7
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Thanks Ritchie,

considering the last point, I am convinced with what you are saying. My point is how you can build effective piece of software if you are not acquainted with the full stack of tools you are given. Suppose I give you 1000 ones and you say just fine, I will learn the basic 100 (or maybe less) and learn the rest as I keep going when I need them. How would you know that you would pick the right one when you need it? Even experienced developers may not have perspective of the software you are trying to make and therefore won't be able to make full judgement. I'm really confused here and don't know what to do.
 
Khaled Abolaynain
Greenhorn
Posts: 7
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Welcome to the discussion Jesper,

OK, you made a really good point here. We can do the same thing in multiple ways. But now I'm letting myself to some random incidence. I always talk to myself that when creating something new, it will be the intersection of different technologies, so if I roll up my sleeves and try to master each one alone, it would be impossible by all means to even start to produce something. Maybe I should just focus on building something and stop overthinking about it!
 
Campbell Ritchie
Sheriff
Posts: 53532
126
  • Likes 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Khaled Abolaynain wrote:. . . . When learning a new language, do I have to know every spec of the language? . . . .
No. You will never know all the specs, and if you ever do learn them, new specs will be developed. You shou‍ld program with what you know, and gradually learn more. Nobody uses 1000 tools for anything. Learn how to use ten tools and use them. We have enough experience to recognise three different ways to do something:-
  • 1: The way I would do it.
  • 2: A different correct way to do it.
  • 3: A bad way to do it.
  • Even now, beginners can hit on a new way to do things which we hadn't thought of.
     
    Winston Gutkowski
    Bartender
    Posts: 10573
    65
    Eclipse IDE Hibernate Ubuntu
    • Likes 2
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Khaled Abolaynain wrote:Maybe I should just focus on building something and stop overthinking about it!

    That's probably a good place to start.

    At the same time: don't be too ambitious. We get lots of posts from beginners who want to write their own chat rooms, or video games, or the next Deep Blue - and it simply ain't gonna happen. Or at least, not for a long time.

    Ideally, you want to pick something that's just beyond your current capabilities, but not too far; otherwise you're likely to get frustrated. So, for example, if you haven't used databases yet, pick a reasonably simple task that uses a database to store information. Likewise with "webby" tools: start simple, and build up gradually.

    The difference between a beginner and an expert has less to do with knowing exactly how to do every little thing (ie, encyclopedic knowledge), but knowing where to look for answers.

    For example, if someone asked me to write a JSON program, I'd probably spend half an hour cursing them because I'm not familiar with it; but then I'd roll my sleeves up, get onto Google, and start reading - and my advantage is that I'll have used similar tools before, so I'll have a rough idea how they work (in my case, very rough ).

    A final point: Documentation is incredibly important (and I say that as someone who doesn't particularly enjoy it), so whatever language you're learning, I'd say that getting familiar with its documentation system - or something like Doxygen if it doesn't have one built in - should be one of the first "tools" you get familiar with.

    HIH

    Winston
     
    Khaled Abolaynain
    Greenhorn
    Posts: 7
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Campbell Ritchie wrote:No. You will never know all the specs, and if you ever do learn them, new specs will be developed. You shou‍ld program with what you know, and gradually learn more. Nobody uses 1000 tools for anything. Learn how to use ten tools and use them. We have enough experience to recognise three different ways to do something:-
  • 1: The way I would do it.
  • 2: A different correct way to do it.
  • 3: A bad way to do it.
  • Even now, beginners can hit on a new way to do things which we hadn't thought of.


    I will start on something and see where it leads me.


    Winston Gutkowski wrote:Ideally, you want to pick something that's just beyond your current capabilities, but not too far; otherwise you're likely to get frustrated. So, for example, if you haven't used databases yet, pick a reasonably simple task that uses a database to store information. Likewise with "webby" tools: start simple, and build up gradually.


    I'm thinking about a web crawler. Wish me luck!
     
    Carey Brown
    Saloon Keeper
    Posts: 2439
    33
    Eclipse IDE Firefox Browser Java MySQL Database VI Editor Windows
    • Likes 1
    • Mark post as helpful
    • send pies
    • Quote
    • Report post to moderator
    Khaled Abolaynain wrote:I'm thinking about a web crawler. Wish me luck!

    I've written a few crawlers, the first ones were written from scratch at a very low level. Not too long ago I updated one and decided to use the jsoup library instead of a bulk of my hand written stuff. I highly recommend looking into jsoup if you want to write your own crawler. Good luck.
     
    • Post Reply Bookmark Topic Watch Topic
    • New Topic
    Boost this thread!