Documentation

Getting Started

The README file in the top level
directory of the source code contains everything you need to get started: how
to get the code in the first place, how to configure and build it, and how to
use java-gnome as a library in your projects.

While not a complete tutorials in themselves, we have a growing number
of small example applications that ship with the source, including one
for the complex TreeView / TreeModel API. See
doc/examples/START
for links to those that have been formatted for web viewing, but remember all
the source code is always viewable online if you don't have a checkout handy.
Just pull up the
'mainline'
branch and navigate to
doc/examples/. The same goes for the rest
of the java-gnome code base; it's all there, including the sources for this website.

Tutorials

Tutorials to get people started and guides about how to use the more
complex APIs are still a work in progress. They will start appearing on this
website in the coming months.

API Documentation

We have put considerable effort into ensuring the java-gnome bindings are
easily usable for people using IDEs like Eclipse, and a big part of that is
having useful JavaDoc so that the help popups you get when you hover over a
class or method helps to the programmer figure out what they need to do in
that context.

The API documentation in the underlying GNOME libraries tends to be sparse
and is very much in the reference style. That's great if you already know what
you're doing and just need to look something up, but isn't much help if you
are trying to figure out how to use a library in the first place. Because of
our focus on approachability, we take a somewhat different approach. The API
documentation in java-gnome is in a more conversational style and is squarely
aimed at helping people learn GTK. Where possible we also include code
snippets to help you understand how to use the APIs,

The API documentation is of course generated by javadoc when
you build the source code and is located at doc/api/4.1/. The
canonical public version of the JavaDoc is hosted here; you
can link to it from your own JavaDoc if you like.

Contributing

java-gnome is an Open Source project, and as such is the sum of the
contributions of the hackers who actually write the bindings code, the
maintainers who take care of library's build system and do releases, the
packagers downstream who make the software available in their distributions,
and of course you, the developers using the library to write your
applications. who send in bug reports and feedback.

Providing complete coverage of the underlying GTK and GNOME libraries is a
mammoth task and you are welcome to get involved!

java-gnome has been carefully designed to be extensible, maintainable,
and above all easy to hack on. Like any large project, though, there are
complexities and common practises that you will want to be on top of before
trying to work on it yourself.

Anyone wishing to contribute to the java-gnome project is therefore advised
to read the top level HACKING file
before doing anything else. It provides instructions on how to checkout the
source code in such a way that you can easily work on your own branches, tips
on how to go about learning the internals of the bindings, and links to the
style guide.

The source code contains considerable reference material about the
background of the project, the design constraints which governed the
re-engineering effort and discussion of the architecture we arrived at. Much
of this documentation is made available here on this website, cunningly
rendered into HTML form.

A good starting point is the doc/design/START file, which
links to each of the other documents in that directory.

In order to meet our quality and approachability goals, we have put in
place certain guidelines to help keep us co-ordinated and to minimize
friction. If you'd like to ensure that code or documentation you might choose
to send in will be accepted, please read the documents in the
doc/style/ directory carefully. They are in essence an extension
of the HACKING file and together with the design documentation
tell you everything you need to know to be able to contribute to java-gnome.