In the last days I have found the componed based entity system.
I think i understand and know how it works, but if I try to implement it, I get a lot of problems.
Here a diagram with the most Problems:
http://s7.directupload.net/file/d/3327/pzy7kanj_jpg.htm
And I wonder me, can I add the same component twice to an entity, or should I dont allow this?
If no, how I can add multiple sprites to an Entity?
And if a make a CollisionComponent or a Physik Component, the Physik and the MoveComponent must communicate, right ?
I hope anyone can me help.
Here I have made another diagram, from Ideas:
http://s1.directupload.net/images/130725/5p83qysu.jpg
Ok there seem to be a lot of related questions between this post and the diagrams you linked to. The answer to these questions are 'it depends.' and I am guessing you would like some guidance on the subject of CBSEs rather than one line answers to all of your questions. Rather than try and regurgitate the discussion based on similar queries I will post some links here that should get you thinking more about these issues.
First there is the ES wiki. This wiki is still in its infancy, but it holds some great discussion on entity systems.
Next, there some really productive discussion over at gamedev stack exchange (maybe this question should be moved there as well). First take a look at this question, it's a good starting point because it explains why there are no clear trends in ES design (when that answer was written) and from what I've seen it still holds true today. Then there is an absolutely amazing answer given by Byte56 that explains the basics of the system-component approach extremely well, and is well worth reading even if you think you've already got a handle on it. Next there is a helpful series of questions asked by Yannbane. These questions address some of the finer points in more detail. Here are all three questions. Also, there are some questions on how to integrate input and Game States.
Finally, you should check out some open source entity systems that have had a lot of attention such as Artemis written in Java (There seems to be a server issue right now for that link but this article is a good intro, and there are c# and c++ repositories available, so you can dig into some code). There is also ash written in AS3.
Now I feel I must answer one of your questions directly:
And if a make a CollisionComponent or a Physik Component, the Physik and the MoveComponent must communicate, right ?
From the diagrams you linked to you seem to be using the systems-based approach (similar to artemis). From my reading I believe that this is one area that has been generally agreed on by the community: in the system approach the idea is to centralize the component logic so that (aside from a few simple methods as mentioned in the answer to Yannabe's second question) the component is little more than a data container. So if your components are stored in entities then your systems are required to sift through all of your entities. The systems that require more than one component should be asking each entity for all the components it needs to do its work. If it doesn't find all of those components the system should move on. So based on what you have decided so far the answer is no, components should not be communicating with eachother.
Anyway, good luck on this.
As it currently stands, this question is not a good fit for our Q&A format. We expect answers to be supported by facts, references, or expertise, but this question will likely solicit debate, arguments, polling, or extended discussion. If you feel that this question can be improved and possibly reopened, visit the help center for guidance.
Closed 10 years ago.
I am going to look for a job as a software tester (a SDET maybe), especially for website test. I have some vague impression of this area and got a couple of specific questions as below:
Among so many documents, such as functional spec, design spec, which should I pay more attention to? How to view them in a tester's view?
Any good suggestions about writing test spec?
Any attention should be paid to website test?
These are just some questions I got now, I'll update with more shortly.
I'd like to hear your voice very much. Many thanks.
Credentials: I'm an SDET with 5 years of experience, 2 of those years testing web applications.
1- I'd say testerab has a pretty good answer. There is no single document that you can invariably rely upon across companies or even teams within a single company. Pay attention to whichever document has information.
I'd augment that answer with this advice: Don't be surprised if the documentation is insufficient. Strike up strong relationships with people who help define the product (the dev, the business owner, the program manager, etc.). You will nearly always be relying on them for some of your specifications, since it is difficult to cover everything on paper (and, as you gain expertise as a tester, you will learn to see things that others don't notice). Try to write down any "verbal specs" as you hear them, and ideally get any requests for specification clarification in writing or email. Gathering them all in a public document is wise, and may help to uncover if two people have very different ideas about what the spec "ought" to be.
2- Testerab has a good answer to this question, also, here: How Do You Keep Automated Tests in Synch With Test Plans
"1) Who reads it? 2) Who should probably read it, but currently you suspect they don't bother? (Do you know why they don't bother?) 3) What information do they need to get from it? Does it give them that info? 4) How do you currently present that information? Does that work for your readers/non-readers? 5) What sort of feedback do you need to get from the readers of your test plan? 6) Do you have any regulatory requirements that you need to satisfy with your test planning? "
Test plans, like product specs, will vary greatly depending on the needs of your group. If you are in an Agile group you may spend very little time on your test plan, doing little more than outlining the areas you need to cover - or you might not even have a test plan at all, but just a conversation with the team about what will be sufficient testing for everyone to feel confident about making decisions about the product. Other companies will have very specific guidelines you will need to follow.
Cem Kaner's classic book "Testing Computer Software" is slightly outdated, but still a good place to start and discusses test planning. I'd recommend you buy a copy quite strongly, unless someone can recommend something as authoritative that is more current. Last I heard, this was still the software testing book.
3- I'm having a little trouble understanding this question, but will do my best. Do you mean, what specifically will you need to know to test websites? First, what do you mean by websites? Do you mean web applications? If so, you will probably need to understand server / client architecture, web services, databases and basic SQL, at least rudimentary security testing, integration testing, functional testing, and will benefit from an understanding or specialization in performance testing, load testing, more security testing, and familiarity with web GUI testing with Selenium or Watir.
Some helpful things for us to know to help you get started:
How much experience do you have, both as a developer and as a tester? If you are just getting started in your career, what is your educational background?
How much experience do you have working with web applications, and in what roles (dev, test, PM, etc.)?
And, you might want to try asking some of these questions over at http://www.softwaretestingclub.com - this is a site for software testers to build community. You will get a lot of good advice and support there, so long as you are active in the community, and many of the most influential software test writers hang out there. If you do stop by there, feel free to look me up!
Hope this helps!
Edit: Added some info to answer q. #2 and to mention Cem Kaner's book.
I'm a developer with 2 years .NET experience and 1.5 years previous testing experience and an ISTQB/ISEB Foundation qualification.
To answer your questions:
1: A test manager will (typically) have a test plan and awareness of the specification documents to be tested against. Using what a developer is using is a good start. If the development methodology is agile this will probably be "user story".
A good way to look at the documents is to go through and look at where individual elements of functionality are specified and create steps to exercise them (see some of the functional techniques below).
2: What do you mean by "test spec"?
You will need to prioritise the areas of the application that need testing and understand the coverage needed. A "Test case spec". (or test script) will fit into higher level documents (like Test Plans, and Test Strategies) can be efficiently and effectively written using some Black box (Functional) techniques including:
Equivalence Partitioning,
Boundary Value Analysis,
Decision Tables,
State Transition analysis,
Use Case analysis (which could be based on a user story)
to come up with scripts that contain test cases. These techniques can be looked up online.
White box (Structural) testing involves an awareness of the code and includes:
Statement Coverage,
Decision coverage
If you're are looking at a website, this may involve JavaScript; QUnit is a testing framework for automating JavaScript testing and would be useful to research. NUnit is a commonly used test framework for .NET applications (including web applications) - NUnit was ported from its Java equivanlent JUnit and has been expanded (most probably owing to the popularity of .NET).
3: I don't understand what you mean by this? A web application will need to be tested in many different ways, and contains server and client functionality that will be tested using different techniques and the testing needs will need to be analysed. It will depend on the project.
As mentioned in other answers there are also other types of testing:
Unit - modular testing of functions at the lowest possible levels
Integration - testing functionality between different functional areas
Regression - testing to ensure that previously working functionality hasn't been broken by changes
System testing (Functional) - ensuring that the code/system under test is working as specified
System testing (Non-functional) - ensuring that aspects of the system that may not be specified are appropriate e.g. performance, load, stress, interoperability, maintainability, reliability, portability, usability
Acceptance (something called User Acceptance Testing or UAT) - ensuring that the system under test is fit for use
As mentioned in other answers, you will be retesting existing defects and inclusion of these to your test scripts is a good idea.
Hopefully this answer has given you a lot of food for thought and a good base for research. Testing qualifications or a role as a Junior Tester in an established team to build your understanding and experience could prove to be very useful.
"Among so many documents, such as functional spec, design spec, which should I pay more attention to? How to view them in a tester's view?"
Being able to extract useful information from many different sources of documentation is a critical skill for a tester, so you're right to identify that as an area you need to look at. The documents you need to look at will vary from project to project, and from company to company, so there isn't one good answer about what document you need to look at - but having good specification analysis skills will mean you'll be able to cope with whatever you're given.
For that, I'd strongly recommend this BBST course on specification based testing - it will show you how to analyse specifications, applying the Satisfice Heuristic Test Strategy model. That should also help you with your second question about writing a test spec.
http://www.testingeducation.org/BBST/BBSTSpecificationTesting.html
I'd recommend the BBST courses in general - the course materials are all available freely online, at the website above.
If you're really serious about testing, you should also consider taking the online course from the Association of Software Testing. The Foundations course is free to members, and you'll get the opportunity to practice your skills online, gain really valuable feedback on how you present yourself and your ideas, and you'll also meet a lot of outstanding testers, both as fellow pupils and as instructors. It's hard work - but if you're willing to put the effort in you will really get a tremendous amount out of it. Being able to discuss the basics with other people will really help you to get a deeper understanding.
my 50c
If you don't have test specs, or any kind of specs, you can transform your bug reports into test plan.
For each bug report that occurs, create one test item. That way - you'll have list of tests that you can follow when doing regression testing.
I have been interested in formal methods for some time. I have used formal methods to reason about some very specific sub-areas of a few projects I have been working on. I was never able to convince other team members to try the same let alone specify an entire domain with a formal method.
One method I have found particularly interesting is Alloy. I think that it may "scale" better as foundation for an entire project because it is conceptually and notationally very close to actual programming languages. Furthermore, the tools are quite solid so that the benefits of model verification are readily available.
I'd be very much interested to hear about any real-world experiences you folks might have had with using Alloy in your projects. Do you feel that it has helped you in designing a better domain model? Did find errors in your domain model during verification? Would you use it again?
I've used Alloy on a few projects and have found it helpful; on some but not all of those projects I have been able to persuade others involved to use Alloy as well, or at least to work with the Alloy models I wrote. These projects may or may not be what you have in mind in asking for 'real-world' projects, but they certainly took place in the part of the real world I work in.
In 2006 and 2007 I created a partial Alloy model for the then-current draft of the W3C XProc specification; as far as I could tell, most members of the working group never read the paper I wrote (at http://www.w3.org/XML/XProc/2006/12/alloy-models/models.html); they said "Oh, we changed that part of the spec last week, so what the model says is no longer relevant". But the paper did manage to persuade the editor of the spec that the abstract 'component' level described in the first draft of the spec was woefully underspecified and needed to be either fully specified or dropped. He dropped it, with (I think) good results for the readability and usability of the spec.
In 2010 I made an Alloy model of the XPath 1.0 data model, which uncovered some glitches in the specification. The reaction of most interested parties (including the W3C working group responsible for maintaining the XPath 1.0 spec) has, unfortunately, not been encouraging.
A research project I'm involved with has used Alloy to model the MLCD Overlap Corpus, a collection of sample documents and related information we are creating (hyperlinks suppressed at SO's insistence); the Alloy model found a couple of errors in our initial design for the corpus catalog, so it was well worth the effort.
And we have also used Alloy to formalize some modeling work we have done on the nature of transcription and on the extension of the type/token distinction to document structure (for our paper, look for the 2010 proceedings of Balisage: The Markup Conference). This lies a little bit outside Alloy's usual area of application, as it has nothing to do with software design, but Alloy's ability to check models for consistency and generate instances has been invaluable in showing us some of the logical consequences of this or that possible axiom for our model.
To answer your specific questions: yes, Alloy has helped me specify cleaner domain models, and yes, it has found errors and glitches. They have often been small, for the reasons Daniel Jackson explains in his book Software Abstractions: first, if you use models during design, you catch errors early, when everything is still small. And, second (in Jackson's words), "In hindsight, most software design issues are trivial."
He continues: "But if you don't address them head-on, trivial issues have a nasty habit of becoming nontrivial." My experience amply confirms this. Much better to head off such problems early. So yes, I will use Alloy again.
Yes, I've used Alloy and it's cousins industrially. Alloy has been most helpful in convincing me that my models weren't wildly wrong---or rather, showing me where they were wrong and gave rise to silly results. Other more specific tools, like Song's Athena and Guttman and Ramsdell's CPSA have been more useful in their narrower domains. What more would you like to hear about?
Belatedly adding to this thread... Eunsuk Kang has recently applied Alloy to perform security analyses of web APIs for some start ups (following many applications of Alloy in security such as Apurva's analysis of OAuth and Barth et al's analysis of browser based security mechanisms for CSRF etc); Pamela Zave has been working on an impressive analysis of Chord, a peer to peer storage system, and has recently written up a fix to the original algorithm.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
I have always liked the documentation on Java APIs, generally speaking, but I know some people consider them lacking. So I'm wondering, what do you consider a good example of API documentation?
Please, include a link or an actual example in any answer. I want to have references that I (and others, of course) can use to improve our own documents.
A good documentation MUST have:
datatypes specs - often more essential than actual functions. Do NOT treat this lightly.
function specs (this is obvious). Including What given function does, why it does it (if not obvious), and caveats if any.
an introduction document that binds the whole into a logical entity, explaining the intentions, correct usage patterns and ideas beyond the scope of actual API code. Normally you are given 50 different functions and you don't know which must be used, which shouldn't be used outside of specific cases, which are recommended to more obscure alternatives and why must they be used that way.
examples. Sometimes they are more important than all the rest
I know how to draw an arbitrary shape of arbitrary color in GTK+. I still have no clue why a change of drawing color requires three quite long lines of very obscure, quite unintuitive lines of code. Remembering SVGAlib's setcolorRGB(r,g,b); draw(x1,y1,x2,y2); I find it really hard to comprehend what possessed the authors of GTK+ to complicate things so much. Maybe if they explained the underlying concepts instead of just documenting functions that use them, I'd understand...
Another example: yesterday I got an answer that allowed me to understand SQLite. I understood a function extracting data from a column returns signed long long. I understood the integer columns could be 1,2,4,6 and 8 bytes long. I understood I can define a column as "UNSIGNED INT8", or "TINYINT". I didn't quite get what "affinity" meant, I just knew both had "INTEGER" affinity. I spent hours seeking whether timestamps should be UNSIGNED INTEGER or INT8, whether INT8 is 8-digits or 8-bytes, and what is the name of that esoteric 6-byte int?
What I missed was that "UNSIGNED INT8", "TINYINT" and the like are all a syntactic sugar synonyms for "INTEGER" type (which is always signed long long), and the lengths given are for internal disk storage only, are adjusted automatically and transparently to fit any value on least number of bits and are totally invisible and inaccessible from the API side.
Actually the iPhone (really Mac Cocoa/framework) documentation has gotten pretty good. The features I like are:
Very easy jump to docs from the API.
Well formatted and the code snippets
you would want to copy and paste
(like method signatures) stand out.
Links to projects with sample code
right from the docs.
Automated document refresh mechanism,
but by default docs are all local to
start (so you can live with a flaky
internet connection).
Easy way to switch between variants
of documentation (to see different
versions of the OS), and also select
which sets of documentation to run
searches against.
An overview section explains what the
class is for, followed by a section
breaking out methods grouped by
purpose (methods to create and
object, methods to query for data,
methods to work with type
conversions, etc), followed by the
detailed method explanations.
I also personally really liked Javadoc and the Java system documentation (I used that for many years), I found a benefit there was it was a little easier to make your own custom docs for your own classes that flowed well with the system docs. XCode lets you also use Doxygen to generate documentation for your own classes, but it would take a but more work to format it as well as the system class docs, in part because the system framework documents have more formatting applied.
A good API will have the following characteristics:
Easy to learn
Easy to use, even without documentation
Hard to misuse
Easy to read and maintain code that uses it
Sufficiently powerful to satisfy requirements
Easy to extend
Appropriate to audience
The most common mistake I see in API design is when developers feel auto-generated XML commenting is sufficient, and then precede to auto-generate their API based off of the XML comments. Here's what I'm talking about:
///<summary>
/// Performs ObscureFunction to ObscureClass using ObscureArgument
///</summary>
void ObscureClass.ObscureFunction(ObscureArgument) { ... }
API's like the one above are only counter-productive and frustrate the developer using the API. Good API documentation should give developers hints as to how to use API and give them insight into certain facets of the API they otherwise would not notice.
I personally believe a perfect example of good documentation is PHP's documentation:
For an example:
http://www.php.net/manual/en/function.fopen.php
I think effective documentation includes:
Parameter listing
(Useful) description of the parameter
If they parameters are a string, list
out and EXPLAIN every possible
possible parameter
Return values on both successful
execution and non-successful
execution
Any exceptions/errors it can raise
Examples (THE MOST IMPORTANT imo)
Optionally:
Changelog
Notes/Examples from other users
Whenever I look up something in the PHP documentation I almost know exactly how to use it without having to scour the internet to find "better" examples. Usually the only time which I need to search the internet is when I need to find how to use a set of functions for a specific purpose. Otherwise, I think the PHP documentation is the greatest example of excellent documentation.
What is think is an example of a alright documentation is Python's:
http://docs.python.org/py3k/library/array.html
It lists out the methods but it doesn't do a good job of actually explaining in depth what it is, and how to use it. Especially when you compare it to the PHP docs.
Here is some really bad documentation: Databinder Dispatch. Dispatch is a Scala library for HTTP that abstracts away the (Java) Apache Commons HTTP library.
It uses a lot of functional-syntax magic which not everyone is going to be very clear on, but provides no clear explanation of it, nor the design decisions behind it. The Scaladocs aren't useful because it isn't a traditional Java-style library. To really understand what is going on, you basically have to read the source code and you have to read a load of blog posts with examples.
The documentation succeeds in making me feel stupid and inferior and it certainly doesn't succeed in helping me do what I need to do. The flipside is most of the documentation I see in the Ruby community - both RDoc and in FAQs/websites/etc. Don't just do the Javadoc - you need to provide more comprehensive documentation.
Answer the question: "how do I do X with Y?" You may know the answer. I don't.
My main criteria is - tell me everything I need to know and everything I'll ever want to know.
QT has pretty decent docs:
http://doc.qt.digia.com/4.5/index.html
Win32 MSDN is also pretty good although it didn't age well.
The java docs are horrible to me. They constantly tell me everything I don't want to know and nothing of what I do want to know. The .NET docs has a similar tendency although the problem there is mostly the extreme wordyness, overflow of so much superfluous details and so much god damn pages. Why can't I see both the summary and the methods of a class in the same page?
I like Twitter's documentation. To me a good API is up to date, easy to read and contains examples.
I think that a good API document needs to clearly explain:
What problem this API solves
When you should use it
When you shouldn't use it
Actual code showing "best practice" usage of the API
Not quite API documentation but nevertheless quite useful is the Oracle database documentation, e.g. for the SELECT statement. I like the inclusion of diagrams which helps to clarify the usage for example.
Just a few thoughts...
Examples - win32 API documentation is better than iPhone's because of:
(short) code examples
I vote for any API doc with small and make-sense examples
Don't ever never show "Form1", "asdf", "testing users" in screen shots or sample codes
good API is solving real world problems and there should be some meaningful examples
Don't auto-gen doc
documentation should not be done during writing code (or by the same guy)
doc is for a stranger, whom the programmers usually don't care of
Avoid ___V2 version of API
but it's not a doc issue
Basically, tell the story of the class at the class level. Why is this here? What should it do? What should be in here? Who wrote it?
Tell the story of methods at the method level. What does this do? No matter how accurate your methods names are, 20-30 characters just won't always cut it for descriptiveness.
#author:
Who wrote this? Who's proud of it? Who should be ashamed of their work?
Interface level documentation tells me:
what should this do?
what will it return?
Implementation level documentation tells me:
how does it do it? what kind of algorithm? what sort of system load?
what conditions might cause a problem? will null input cause an issue? are negative numbers okay?
Class level documentation tells me:
what goes here? what kind of methods should I expect to find?
what does this class represent?
#Deprecated tells me:
why is this planned for removal?
when is it expected to be removed?
what is the suggested replacement?
If something is final:
why didn't you want me to extend this?
If something is static:
remind me in the class level doc, at least implicitly.
In general: you're writing these for the next developer to use if and when you hit the lottery. You don't want to feel guilty about quitting and buying a yacht, so pay a bit of attention to clarity, and don't assume you're writing for yourself.
As the side benefit, when someone asks you to work with the same code two years from now and you've forgotten all about it, you're going to benefit massively from good in-code documentation.
First point for a great API-documentation is a good naming of the API itself. The names of methods and parameters should be say all. If the language in question is statically typed, use enums instead of String- or int-constants as parameters, to select between a limited set of choices. Which options are possible can now be seen in the type of the parameter.
The 'soft-part' of documentation (text, not code) should cover border-cases (what happens if I give null as parameter) and the documentation of the class should contain a usage-example.
Good documentation should have at least the following:
When an argument has additional limitations beyond its type, they need to be fully specified.
Description of the [required] state of an object before calling the method.
Description of the state of an object after calling the method.
Full description of error information provided by the method (return values, possible exceptions). Simply naming them is unacceptable.
Good example: Throws ArgumentOutOfRangeException if index is less than 0 -or- index is greater than or equal to Count.
Bad example: Returns 0 for success or one of the following E_INVALIDARG, etc... (without specifying what makes an argument invalid). This is standard "FU developer" approach taken in the PS3 SDK.
In addition, the following are useful:
Description of the state of an object if an exception is thrown by the method.
Best practices regarding classes and groups of classes (say for exceptions in .NET) in the API.
Example usage.
Based on this:
An example of great documentation is the MSDN library.
To be fair, the online version of this does suffer from difficulty of navigation in cases.
An example of terrible documentation is the PS3 SDK. Learning an API requires extensive testing of method arguments for guessing what may or may not be the actual requirements and behavior of any given method.
IMO examples are the best documentation.
I really like the Qt4 Documentation, it first confronts you only with the essential information you need to get things working, and if you want to dig deeper, it reveals all the gory details in subsections.
What I really love, is the fact that they built the whole documentation into Qt Creator, which provides context sensitive help and short examples whenever you need them.
One thing I've always wanted to see in documentation: A "rationale" paragraph for each function or class. Why is this function there? What was it built for? What does it provide that cannot be achieved in any other way? If the answer is "nothing" (and surprisingly frequently it is), what is it a shorthand for, and why is that thing important enough to have its own function?
This paragraph should be easy to write - if it's not, it's probably a sign of a dubious interface.
I have recently come across this documentation (Lift JSON's library), which seems to be a good example of what many people have asked for: nice overview, good example, use cases, intent, etc.
i like my documentation to have a brief overview at the top, with fully featured examples below, and discussions under these! I'm surprised that few include simple function arguments with their required variable types and default values, especially in php!
I'm afraid i can't really give an example because i havent trawled through to find which ones my favourite, however i know this probably doesn't count because its unofficial but Kohana 3.0's Unofficial Wiki By Kerkness is just brilliant! and the Kohana 2.34 documentation is pretty well laid out too, well at least for me. What do you guys think?
Most people have listed the points making up good API documentation, so I am not going to repeat those (data type specs, examples, etc.). I'm just going to provide an example which I think illustrates how it should be done:
Unity Application Block (Go to the Download section for the CHM)
All the people involved in this project have done a great job of documenting it and how it should be used. Apart from the API reference and detailed method description, there are a lot of articles and samples which give you the big picture, the why and how. The projects with such good documentation are rare, at least the ones I use and know about.
The only criteria for documentation quality is that it speeds up development. If you need to know how something works, you go and read docs. One doc is better than another if you've understood everything from first doc faster than from from second.
Any other qualities are subjective. Styles, cross-references, descriptions… I know people who likes to read books. Book-styled doc (with contents/index/etc.) will be good for him. Another my friend likes to doc everything inside code. When he downloads new library, he gets sources and "reads" them instead of docs.
I, personally, like JavaDocs. Like Apple dev docs with the exception of lower-level parts, for example, Obj-C runtime (reference part) is described awfully. Several website APIs have docs I like also.
Don't like MSDN (it's good in general but there are too many variants of the same document, I get lost often).
Documentation is only a part of the big picture, API design. And one could argue the latter is much more important than just the naming. Think of meaningful non-duplicating method names, etc.
I would definitely recommend watching Josh Bloch's presentation about this:
http://www.infoq.com/presentations/effective-api-design OR http://www.youtube.com/watch?v=aAb7hSCtvGw
This covers not only what you're looking for but much more.
Lots of practical, real-world examples are a must. The recent rewrite of jQuery's API documentation is a good example, as well as Django's legendary docs.
The best documentation I've found is Python. You can use sphinx to generate the source documentation into HTML, LaTeX and others, and also generate docs from source files; the API doc you are looking for.
API docs is not only the quality of the final documentation, but also how easy is for the developers and/or technical writers to actually write it, so pick a tool that make the work easier.
Most things about good documentation have already been mentioned, but I think there is one aspect about the JavaDoc way of API documentation that is lacking: making it easy to distinguish between the usage scenarios of all the different classes and interfaces, especially distinguishing between classes that should be used by a library client and those that should not.
Often, JavaDoc is pretty much all you get and usually there is no package documentation page. One is then confronted with a list of hundreds or even more of classes: where and how to start? What are typical ways of using the library?
It would be good if there were conventions of how to make it easy to provide this information as part of JavaDoc. Then the generated API documentation could allow for different views for different groups of people -- at a minimum two groups: those who implement the library and those who use it.
I find Google APIs a beautiful example of Good documentation API.
They have:
Bird's eyes view of the entire APIs structure
Overviews of the main features of the single API
Nice and colored examples for a quick feedback
Detailed references
A blog that keep you updated
A google groups that documents problems and solutions
Videos
FAQ
Articles
Presentations
Code Playground
A search engine to crawl inside a pile of documentation
That's it!
When I play with google APIs documentation site, I feel at home.
Go to the Doxygen site and look at the examples of the HTML that it generates. Those are good:
http://www.doxygen.nl/results.html