What is the best way to find javadoc in my projects?

Is there anything better than a batch process:

  • generate your javadoc then
  • set up a local search engine such as Solr?

Is there a javadoc search plugin for Eclipse?

Or a finished product for this?

Context: JavaDoc is great when you know where to look. But I want to support people who are new to the codebase and don’t know where to start. Search + some package level overview documents look like a good solution. Has anyone got the best deal?

Related Q: Search JavaDoc in Eclipse

+7
source share
2 answers

Java 9 seems to add search to the generated Javadoc. Here is the related JEP: http://openjdk.java.net/jeps/225

It seems that the search is not intended to search all the text anywhere in the Javadoc, but rather is limited to "program elements and marked words and phrases in the documentation." However, it can meet your needs if and when your organization can upgrade to Java 9.

+2
source

What Andreas said in his comment on your post. You would do better if you put your efforts into creating some design documents, as well as documents on software, systems and business architecture, which give an idea of ​​10 thousand Feet about how the software is archived, where it works and how, and most importantly, why / that business goals are being completed.

People did more than good, with just one Javadok. Now cut the last paragraph and ask a few questions:

1. Documents of business processes

Context: JavaDoc works great when you know where to look.

Where to look, you are given some kind of entry point into your system, an idea of ​​what it does, and why and for whom. It is unforgivable to look at the code base without having an idea of ​​the business processes that it should support. The document should also document who the main business leaders or business SMEs are (subject matter experts).

Do you have such document (s) that helps new codes with this?

If not, you should do this before deploying the search engine on top of the JavaDoc.

2. Software / system architecture documentation

But I want to support people who are new to the code base and do not know where to start looking.

Well, for this you need what I mentioned above all. Secondly, you need the architectural diagrams of your system, at least its main components, their topology and where they are deployed. Later, a system / network / deployment diagram is implied. It also documents the core SMEs for software components and system-level parts.

Something, anything, even if you like only a 10k foot high view.

Do you have such document (s) that helps new codes with this?

If not, you also need to implement this.

3. Wrong priorities

Search + some overview batch level docs looks like a good solution. Has anyone got the best deal?

It seems to me that this solution is looking for a problem. It would be nice to have, but, in my experience, this adds very little value if you intend to help new visitors get used to the system.

The problem is that you are looking at it from the wrong point of view. You want beginners to become familiar with the code base, when in fact you should always strive to make them familiar with the system .

Code base = / = system.

Actually system -> code base.

Even if we simply focus on the fact that code is what we put in our hands throughout the day, the code exists, runs, changes and has errors in the context of the system. Focusing only on code (or, above all, code) is a surefire way to inculcate the nearsighted look of the system on new visitors (increasing the time to become self-sufficient and productive).

It is always better (time / money reasonable) to understand the system in order to understand the code base (unlike the other).

If you have all of these things in place, then maybe using Solr or Lucene on top of the JavaDoc may be nice, but one of the very few ROIs (you should always think about ROIs, otherwise, you just play the experiments while calculating salary .) In the end, I have never seen a well-implemented Java store implementing this. KISS etc.

Otherwise, doing this instead of attending more serious documentation needs seems like it is interesting to do manicure on the hand, experiencing massive necrosis.

+1
source

All Articles