Show HN: I generated API documentation for all Java packages (docland.io)
I built Docland because I constantly found it frustrating to locate and view API definitions when programming. You'd have to Google the function/class name, skip all the SEO articles, find the page you want, yet the documentation might be poorly formatted or does not support searching.
So I thought it would be really cool to create a documentation site dedicated for programming languages and libraries, so that you can find the docs all in one place with a uniform look. Docland currently only supports Java, but more programming languages can be supported thanks to its modular architecture.
Please try it out and let me know what you think! Also, the process of building Docland was extremely fun and challenging. I'm happy to share about that too.
Thank you!
Martin
53 comments
[ 2.5 ms ] story [ 119 ms ] threadThe pricing seems a bit steep. It isn't an exact competitor, but it reminds me of https://kapeli.com/dash which appears to be $15/year. Annoyingly dash is Mac only so poor linux devs like me can't use it, so having this be a web app is great.
Well you can tell Intellij to just download the sources of libraries used in your project, and then it's ctrl-q on a method to see its javadoc.
I did not look at your project, presumably it does something more to add value to this?
If you write code 90% of the time in a frontend or scripting or other kind of language where a lightweight code editor like VSCode is the peak of productivity — and then have to fix bugs in a Java codebase the other 10% of the time — then you're likely just going to work on the Java project using VSCode, rather than learning a whole extra (more complex!) tool just to increase your Java productivity.
Docland seems like it would be a good and helpful resource for the people who do things that way.
Even Gosling admits that writing Java without an IDE is a fools errand.
Admittedly, it was slow going for a few days when I first was asked to help with the Java codebase. I had never written Java professionally — and I had even (inconveniently) missed out on ever having to write it for school.
But, given that I was already familiar with a number of other languages and their ecosystems (including newer languages influenced by Java!), I could mostly guess what stdlib ADTs and ecosystem libraries probably exist in Java, find them with quick searching when reaching for them, and read the online auto-generated JavaDoc documentation — where and when it existed — to figure out what classes and methods I would need to use to achieve the effect I was picturing.
Once I knew the types and their methods and used them a few times, I didn't need any reference for them any more. (Though I should point out that I wasn't entirely without help; these days, even non-IDE code editors like VSCode or Sublime Text, give you some level of project-level fuzzy symbol search, constant/method/identifier auto-complete, reference/definition chasing, etc. They're just limited in their knowledge to the set of symbols they can extract from the code of the project itself — with no access to the "unreferenced" symbols that an IDE would be loading from the runtime and any project-referenced libraries.)
In learning Java this way, my only actual problem really did come down to the slap-shod nature of JavaDoc documentation! After languages like Elixir, where the docs for literally every version of every package, plus every version of the runtime itself live together on one website (hexdocs.pm) — in a uniform format, and with community conventions for providing usage examples as runnable doc-tests — Java's third-party library docs living on random websites or not even web-published at all was both painful and somewhat mystifying to me at the time.
I do understand now in retrospect, that this is mostly down to Java library authors expecting you to use an IDE... but even then, I still find the lack of care many library authors put into maintaining standardized online documentation very odd. I like to look at the API of a library package as part of comparing/contrasting it to other library packages when deciding which one I should be using — which Java's documentation ecosystem often makes nearly impossible. (Even with a Java IDE, you'd have to create a project that has all of these libraries as dependencies — which might be impossible given dependency conflicts! — just to be able to do that.)
(But hey, it's still better than Python's documentation ecosystem.)
I'm myself a CLI person, and I'd consider myself quite proficient using the shell and console editors like Vim. I know many shortcuts and I manage myself quite well and very fast there.
However, when I do Java development I use an IDE. There's so many things that an IDE does that regular text editors don't (sure, there's ways to hack them to do some subset of those things, but that takes a lot of setup time and they'll always be a subset). Programming efficiency is not about typing fast or speeding up moving a paragraph of code to the end of the file by doing d-}-G-p; but rather to ask the IDE to do a refactor of some code, remove unused dependencies, click on a method to see it's definition or get contextual JavaDoc, to name a few (basic) features that IDE give you,
The things I mentioned (local symbol auto-complete, reference-chasing, global go-to-symbol) are things that modern code editors do by default for any programming language they can syntax-highlight. (And also, unlike with an IDE, they don't require any understanding of a particular "project" format to do so. You can git-clone any random repo, throw it at them, and they'll see a directory tree of source files and blindly index everything in it.)
> ask the IDE to do a refactor of some code, remove unused dependencies,
Honestly, I think I just... haven't ever felt the need to do these things in Java?
When I'm fixing bugs, I'm usually just rewriting one line that calls something to call something else instead. Or adding a check for an edge-case. Or wrapping a blocking call in a semaphore or worker pool. Or making something more idiot-proof by replacing a primitive `int numSeconds` with a Duration. 99% of my "coding" time for a Java problem is actually spent investigating whatever heisenbug brought the problem to me (usually after already passing through a coworker's IDE's debugger, to no avail.) The actual solution I arrive at after such investigation, is usually trivial.
Which is to say, I write Java code, but I never really need to maintain any. I'm not on the team that owns the codebase; I'm just a pinch-hitter there to quickly fix customer-facing DevOps issues discovered in prod.
And, at least for that role — which might admittedly be an unusual one for a Java project — I don't think an IDE would help me get problems solved any faster than I already solve them.
Sure, they can. But as said, they are still quite basic stuff compared to what IDEs do. It's better than nothing, but they don't contribute to productivity as IDEs do.
> Honestly, I think I just... haven't ever felt the need to do these things in Java?
This is surprising for me, but hey, each of us are a different use case.
My recommendation is to try an IDE extensively, and then you decide what suits you better. I did this, and never looked back (for Java programming; I'm still using Vim extensively for general text edition, for example).
That’s really just a small sample of some of the online editing/coding solutions. I personally run vscode locally, but maybe we’re moving towards a day where running local editors and IDEs is the exception.
They can suggest some code, but they are like a dumb autocomplete. Your next sentence about understanding the project itself is the whole point - intellij can give me suggestions for my backend’s endpoints when I write the frontend, and clicking on such a href will jump to the controller.
It’s a pretty magical experience and I would even go as far that I would dare claim I’m writing Java code faster thanks to such a superior IDE than I would write some less verbose other PL.
Yes, they do that because they assume — due to Java being a recommended first language — that they're talking to someone with literally no programming experience. An IDE for a particular language is something that you can just download and start using to write and build and run and debug code in that language. Thus integrated development environment. (And despite Java IDEs themselves being Java apps, they all ship as installers that install their own embedded JREs for the app to run with, and download JDKs on-demand for projects to bind to; so the newbie dev doesn't even need to know what a "language runtime" is or that Java is!)
The alternative, when crafting a video targeting newbie programmers, would be to explain to them — people who might or might not know what a terminal is, what a shell is, what a compiler is, what a JDK is and how to install one, how to invoke javac, what a build system is, how to pick one and set up its project file, how to select a code editor to use, how to save things with non-.txt file extensions and in the right directory structure to make the build system happy, how to invoke the resulting build, etc — how to do all of those (mostly language-neutral!) things, in order to bootstrap their way up to being able to create a single Java main class and run it.
But on the other hand, if you already know five or ten other programming languages when you learn Java — then you'll already have a favorite code editor (and will assume you can just tell it to install a language-support package for the new language); and you'll already know what compilers and build systems are, and will just want to know how those general concepts are implemented for this specific language; and you'll already know how to invoke those things from a shell or from a build script, and how to ask the compiler for its flags, and how to read its man page to figure out what env-vars it looks at; and will just look up the syntax reference for the build system's project metadata files and some examples in other projects, and have one knocked out in two minutes without ever reading its documentation; etc.
You'll know all these things, because these things are the lingua franca of development-time tooling abstractions — the things that stay the same no matter what specific alternate strategies a given language tries to get you to use. As you learn more languages, the language-specific tooling abstractions will drop away, irrelevant outside of their language; but anything you learn about the language-neutral tooling abstractions will be reinforced by each new language.
You'll learn more-and-more to lean on these language-neutral tooling abstractions when learning a new language, because with them, you'll get up to speed in the new language much faster; stumble less when context-switching languages; and have a confidence for "plumbing" tasks like "how should I dockerize this for reproducible builds and low start-up overhead" or "how do I build this in CI with caching" or "where would a linter pre-commit hook plug into this."
> I don't understand why you bothered
Because I consider the mass belief in the need for an IDE to write Java in particular to be "received folk wisdom" with no actual basis in evidence.
I am personally just as productive when writing Java without an IDE, as I am when coding in any other language not designed for an IDE. I know that; I can measure that.
But moreover, from ~20 years of interacting with other software engineers in various roles, my impression is that that most people who code in Java would also be just as productive without an IDE — provided that, like me, they have experience coding without an IDE (probably in a language that doesn't have good IDE support.)
From what I've observed, it's only the junio...
Your real point is that any IDE/tool has a learning curve, but don’t ever mistake avoiding that curve for “peak productivity”
Javadoc already gives you an extremely fast search index and search bar. Granted, it's only in the newest versions of Java.
The real benefit of customizing search is custom ranking and filtering logic. Docland sorts the search results by relevance (matching prefix length and casing) and dedupes overloads. In my (possibly biased) opinion it's easier to use.
Agreed. If you do have performance improvements in mind, I would recommend you bring them up to the Javadoc jdk team. They would definitely take a look if you can point out a faster solution.
https://openjdk.org/projects/javadoc-next/
> That's why the search bar in the official java.base documentation is noticeably laggy.
On my $400 laptop from 2020, I have a response time of <= 0.25 seconds. Are you seeing something different?
* Retina, MBP 14"
Ex. https://docland.io/doc/java/g1/_openjdk/java.base/21.0.2.u13...
That page seems to be mostly wrapped in links incorrectly.
2. The homepage requires you to choose an artifact/package first. Click "java.base" and then you can find SimpleDateFormat with the "search" field on the subsequent page.
The keyboard navigation on the search doesn't work (pressing enter closes the results, doesn't navigate), and I find a search over artifacts to be too limiting for my use-case, but I guess it's not wrong.
The keyboard navigation doesn't work yet, will fix in the next release.
I'm curious. What is "External link resolution"? I'm a bit embarrassed that I don't know, and I've been writing Java / Scala for decades...
Sorry for the confusing terminology -- "External link resolution" just means links to any direct/transitive dependencies will be resolved. It takes more time and memory to generate so by default those links would be broken (marked in red).
A good start would be focusing on what it is, rather than what you did.
This documentation set is not currently available for public access.
Please subscribe to Docland Plus to gain unlimited access and unlock all premium features! "
Increasingly, it feels like the web is a less pleasant experience, albeit stumbling upon the occasional StackOverflow/StackExchange/GitHub discussion that goes in depth on some topic or compares various approaches is still quite useful, for example: https://stackoverflow.com/a/50892881
That said, good luck on your monetization! Probably not for me at the moment, but I'm sure that some people will see the value:
> 403
> Access denied
> This documentation set is not currently available for public access.
> Please subscribe to Docland Plus to gain unlimited access and unlock all premium features!
(looking up commons-lang3, curiously the most popular package under org.apache.commons resolves without the message, but the seemingly re-published ones from elsewhere don't)
In all seriousness, I miss the Contents-tab-style of navigation like I used to do with CHM ages ago.
There was this point in time such that when I opened a CHM I knew I was going to read chapters about use cases, examples, tips and tricks, gotchas and all the way at the bottom I would find the reference API documentation.
Not sure people will pay for "just" a nice (java)doc renderer/ui.
Maybe some sort of API diff for migrations or a maintained collection of OpenRewrite migrations could be a good value add, however that's a lot more complicated to provide.