10 ms·

Show HN: I generated API documentation for all Java packages

74 points by martin_dd 2y ago

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

dinkleberg 2y ago
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 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.
- martin_dd 2y ago
  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.
- fiddlerwoaroof 2y ago
  There’s a viewer for dash docsets on Linux, I think it’s called Zeal. I also use an emacs viewer for them
pandemic_region 2y ago
> 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?
- martin_dd 2y ago
  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!
- derefr 2y ago
  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.
  - koolba 2y ago
    > 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.
    - vips7L 2y ago
      Personally I don’t think Gosling is relevant to Java in 2024. It’s completely different from when he was involved.
pron 2y ago
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?
- martin_dd 2y ago
  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.
davidalayachew 2y ago
> 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.
- martin_dd 2y ago
  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.
  - davidalayachew 2y ago
    > 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/ 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?
    - refulgentis 2y ago
      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"
      - davidalayachew 2y ago
esprehn 2y ago
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-3/java.lang.module/_index.html https://docland.io/doc/java/g1/_openjdk/java.base/21.0.2.u13... That page seems to be mostly wrapped in links incorrectly.
- martin_dd 2y ago
  Thanks for pointing that out, will fix soon.
zmmmmm 2y ago
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.
- re 2y ago
  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.
  - vips7L 2y ago
    It just doesn't work. Lots of known classes don't present anything.
    - danpalmer 2y ago
      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.
      - martin_dd 2y ago
        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.
      - zmmmmm 2y ago
        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).
tanin 2y ago
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...
- martin_dd 2y ago
  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).
pharaohgeek 2y ago
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.
- martin_dd 2y ago
  That's right! It's a custom HTML renderer with custom css and client-side js for navigation and search.
  - saywhanow 2y ago
    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.
ta988 2y ago
"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! "
- sharpshadow 2y ago
  Seems like most of it is behind a paywall. 403 all over the place.
- a57721 2y ago
  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.
8mobile 2y ago
Hi, nice UI and excellent idea for reading the documentation, the price seems exaggerated to me given all the online possibilities.
KronisLV 2y ago
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 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)
amne 2y ago
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.
ysleepy 2y ago
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.
mdaniel 2y ago
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

74 points by martin_dd 2y ago

dinkleberg 2y ago

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

martin_dd 2y ago
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.
fiddlerwoaroof 2y ago
There’s a viewer for dash docsets on Linux, I think it’s called Zeal. I also use an emacs viewer for them

pandemic_region 2y ago

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

martin_dd 2y ago
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!
derefr 2y ago
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.
- koolba 2y ago
  > 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.
  - vips7L 2y ago
    Personally I don’t think Gosling is relevant to Java in 2024. It’s completely different from when he was involved.

pron 2y ago

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?

martin_dd 2y ago
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.

davidalayachew 2y ago

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

martin_dd 2y ago
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.
- davidalayachew 2y ago
  > 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/ 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?
  - refulgentis 2y ago
    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"
    - davidalayachew 2y ago

esprehn 2y ago

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-3/java.lang.module/_index.html https://docland.io/doc/java/g1/_openjdk/java.base/21.0.2.u13... That page seems to be mostly wrapped in links incorrectly.

martin_dd 2y ago
Thanks for pointing that out, will fix soon.

zmmmmm 2y ago

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.

re 2y ago
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.
- vips7L 2y ago
  It just doesn't work. Lots of known classes don't present anything.
  - danpalmer 2y ago
    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.
    - martin_dd 2y ago
      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.
    - zmmmmm 2y ago
      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).

tanin 2y ago

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

martin_dd 2y ago
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).

pharaohgeek 2y ago

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.

martin_dd 2y ago
That's right! It's a custom HTML renderer with custom css and client-side js for navigation and search.
- saywhanow 2y ago
  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.

ta988 2y ago

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

sharpshadow 2y ago
Seems like most of it is behind a paywall. 403 all over the place.
a57721 2y ago
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.

8mobile 2y ago

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

KronisLV 2y ago

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

amne 2y ago

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.

ysleepy 2y ago

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.

mdaniel 2y ago

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