Hacker News new | past | comments | ask | show | jobs | submit login
Show HN: I generated API documentation for all Java packages (docland.io)
74 points by martin_dd on May 26, 2024 | hide | past | favorite | 52 comments
Hi HN! I'm excited to share a project I've been working on for the past year: Docland. It is an API documentation browser that generates documentation on demand (through compilation, not LLMs) for Java packages. Instead of relying on Javadoc, the built-in doc generator, I created the engine from scratch to give the documentations a modern look, build fast search indexes, and enable link resolution to other packages.

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




> Instead of relying on Javadoc, the built-in doc generator, I created the engine from scratch to give the documentations a modern look, build fast search indexes, and enable link resolution to other packages.

Javadoc already gives you an extremely fast search index and search bar. Granted, it's only in the newest versions of Java.


Author here. Yes, the search bar is nice already, and the performance is good enough for most use cases. Fun fact, javadoc's search is O(n), Docland uses binary search so it's O(log2n). That's why the search bar in the official java.base documentation is noticeably laggy.

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.


> Author here. Yes, the search bar is nice already, and the performance is good enough for most use cases.

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?


I don't see a search bar, and as long as they might be looking at this thread, something strange is going on, everything is sized absurdly small, as if its rendering my HiDPI* display at 1x

* Retina, MBP 14"


https://docs.oracle.com/en/java/javase/22/docs/api/index.htm...


> 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.

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?


Why assume that everyone who touches Java code, uses an IDE to do so?

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.


> Why assume that everyone who touches Java code, uses an IDE to do so?

Even Gosling admits that writing Java without an IDE is a fools errand.


I mean, I wasn't being facetious; I am the person I described. I code Java (the 10% of the time that I have to touch it) using Sublime Text and a terminal. Never learned an IDE. I still seem to get things done faster than the IDE people I know.

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.)


My experience is that you are slower/way slower without an IDE.

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,


> sure, there's ways to hack them to do some subset of those things, but that takes a lot of setup time

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.


> 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

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.


Modern editors with good Java support, while not being full-fledged IDEs, rely on a Java language server. They don't blindly index .java files in a directory. It is also very desirable to index external dependencies.


> 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

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).


As someone who really likes IDE's especially since Java has such good free ones like intejilli I think they are awesome but for changing one line of code it's overkill. I often just use online editors for quick stuff if I can.


online editors???


There are quite a few different environments for online IDEs and code editors, these days. Try googling some of these: “aws cloud9” “vscode web” “GitHub codespaces”

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.


Most people write Java with an IDE. In fact, if you search for Java tutorials on YouTube, they first thing they tell you to do is to install an IDE. In other words, I don't understand why you bothered to waste your time writing such a long comment that are not applicable and have no use to others, as if you are showing off or something.


> they first thing they tell you to do is to install an IDE

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 junior engineers, whose only fluent languages are IDE-reliant and so have never done non-IDE development, that truly benefit from a productivity boost when using IDEs. For them, the IDE is acting as training wheels — making them "more productive" insofar as without it, they wouldn't have a solid foundation of "programming reflexes" to rely on. And I mean that in multiple senses — it acts as training wheels for:

• their language-toolchain tooling reflexes (e.g. being able to quickly modify+build+test a thing without a hotkey that just "does that")

• their code-editing reflexes (e.g. knowing their editor well-enough to be able to quickly refactor one class into two with editing gestures rather than a language-specific macro);

• their language reflexes (e.g. building up an intuition for which stdlib package a given class lives in, to write imports quickly — or to take advantage of fully-qualified class names to avoid single-use imports!; being able to remember long method names by "compressing" them, using the library of commonly-used identifier fragments in your head; remembering what parameters a given ADT's methods take by building a greater sense of how those APIs analogize to APIs in other languages; etc.)

> as if you are showing off or something

I was citing my own personal experience as an existence proof of how it's possible to be productive in Java without an IDE, because anecdata is at least better than no data at all. But I didn't mean to suggest I was exceptional; of my other engineer friends who code in multiple languages, not a one of them pulls out an IDE for IDE-supportive languages.

Do you interpret Morpheus to be bragging when he describes to Neo what's outside of the Matrix? My goal here is the same: to point out that your belief in IDEs being more productive might be due more to being in a programming-culture bubble; and that there is a world outside that bubble that believes something different.

> waste your time writing such a long comment

I (and from my observation, many others) use HN comments mostly as a space for blogging. Specifically, for "shooting from the hip" blog posts — the kind where I don't like them enough to spend time polishing it and condensing it to post it onto an actual blog.


Personally I don’t think Gosling is relevant to Java in 2024. It’s completely different from when he was involved.


I downvoted you; whether Gosling is relevant or not doesn't address the core argument that Java is hard to use without IDE.


It’s not hard. I’ve done it in neovim and vscode. Evoking Gosling as if his opinion matters more when he isn’t involved in Java made my comment relevant.


Thank you for the kind words! Even though I'm a Jetbrains all products pack user myself, totally agree with you that it's still useful to have API references alongside your main editor/IDE. If there's enough interest I'd love to build a VSCode plugin for Docland.


> where a lightweight code editor like VSCode is the peak of productivity

Your real point is that any IDE/tool has a learning curve, but don’t ever mistake avoiding that curve for “peak productivity”


Author here. The value add is a better browsing experience: with Docland, you can navigate across the class hierarchy, search symbols quickly, and view the package content at a glance. Feel free to check it out!


Is it safe to assume you’ve written a custom Javadoc renderer? If so, this is long overdue. The existing renderer for Javadocs produces ugly — though functional — results. I’d love to see an alternative rendered implemented to generate something more visually and user-friendly.


That's right! It's a custom HTML renderer with custom css and client-side js for navigation and search.


This looks promising, but it needs a far improved introduction.

A good start would be focusing on what it is, rather than what you did.


Nice work, this looks great. I'm not a Java dev, so I can't say I'll be using this, but the design is nice and simple, and it is fast.

The 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.


Thank you for checking it out! I'm aware of Kapeli's Dash and do think it's a great piece of software. Though, Docland is great at dynamically generating documentation for libraries from source code (i.e. it could work for any software library), while Dash's strength is its ability to serve static documentation sets.


There’s a viewer for dash docsets on Linux, I think it’s called Zeal. I also use an emacs viewer for them


This looks pretty nice and usable! Though a lot of the time I can just get the docs inside of JetBrains IDEs, without needing to open a browser. Or more recently, for the simpler stuff, LLM based autocomplete is also pretty nice.

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)


I think that's the first time I've seen <script type=module> in the wild

  <script type="module">
  import { runDocpageEntrypoint } from "/build/index.3bb1c1f7.mjs";
  runDocpageEntrypoint("Production", "");
  </script>
But, if I may make a suggestion, it would be so much nicer if those <code> blocks had one of the many JS syntax highlighter libraries applied to them


I appreciate the modern look, but it looks like you have some bugs in how it generates links.

Ex. https://docland.io/doc/java/g1/_openjdk/java.base/21.0.2.u13...

That page seems to be mostly wrapped in links incorrectly.


Thanks for pointing that out, will fix soon.


This is pretty nice. I'll try it out next time I have to look at javadoc. It might be great to improve SEO, so when I search for a Java class in Google, the results show docland.

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...


Thanks, I've done what I could to improve the lighthouse scores. Hoping it will be indexed soon.

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).


Compiled HTML? Sounds familiar.

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.


Looks really nice.

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.


I typed SimpleDateFormat into the search field and pressed enter and nothing happens at all. What am I doing wrong? There's no submit button if there is supposed to be. Firefox / Mac.


1. The text field is actually a filterable "select"-type field, not a raw search. It should show you completions that you should click; if you're not seeing any, you might be encountering some JavaScript error somewhere. It does look like keyboard-only navigation is broken/unsupported, though, which seems important to add -- I'm forced to use my mouse to click the option I want.

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.


It just doesn't work. Lots of known classes don't present anything.


I also tried this as I assumed it was searching all symbols, but it looks like it's only searching artifacts. Once you're into an artifact you get a search within that.

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.


I think I was extra confused because the HN title says it searches "packages" so I assumed that was what it was doing (in a java sense, where a package is the classes inside a library).


Yes, it's searching artifacts. Unfortunately searching symbols is not feasible until I have a larger budget. (Probably need TBs of index)

The keyboard navigation doesn't work yet, will fix in the next release.


thanks! now I understand it, it's fine, but there are definitely some UX things that could be improved to make how it's working obvious from the start.


How do you find all the source files for a project (as they could have a somewhat different organisation)? Do you manually create a rule to find all the sources of a particular coudebase?


It's all automated. Most third-party packages have their source code published as source JAR on Maven central and I just use that. JDK is the only exception, where I use OpenJDK's source code.


Hi, nice UI and excellent idea for reading the documentation, the price seems exaggerated to me given all the online possibilities.


"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! "


I get the same message for every particular artifact that I look up. If almost everything is behind a paywall, I'm fine with javadoc.io.


Seems like most of it is behind a paywall. 403 all over the place.




Consider applying for YC's Fall 2025 batch! Applications are open till Aug 4

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact

Search: