[HN Gopher] Show HN: I generated API documentation for all Java ...
___________________________________________________________________
Show HN: I generated API documentation for all Java packages
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
Author : martin_dd
Score : 38 points
Date : 2024-05-26 12:35 UTC (10 hours ago)
(HTM) web link (docland.io)
(TXT) w3m dump (docland.io)
| dinkleberg wrote:
| 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.
| martin_dd wrote:
| 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 wrote:
| 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 wrote:
| > 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 wrote:
| 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 wrote:
| 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 wrote:
| > 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 wrote:
| Personally I don't think Gosling is relevant to Java in
| 2024. It's completely different from when he was involved.
| derefr wrote:
| 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 maintain 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 symbolic 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 "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.)
| ahachete wrote:
| 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,
| martin_dd wrote:
| 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.
| pron wrote:
| 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 wrote:
| 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 wrote:
| > 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 wrote:
| 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.
___________________________________________________________________
(page generated 2024-05-26 23:00 UTC)