On 1/29/22 9:57 AM, Vikram Bakshi wrote:
Hello javadoc developers,
Apologies if this is the wrong place for this type of message - I did
not know where else to reach out.
I have a feature request which I would like to propose for a future
javadoc version: a link to the actual source code of the definition
within the produced javadoc.
Something similar to what Haskell produces is what I am thinking. See
here:
https://hackage.haskell.org/package/base-4.16.0.0/docs/Prelude.html#g:27
You see the type signatures of the functions and their description
just like how it would be for the javadoc produced for a class, but on
the right there is also a button for '#' and 'Source'. The source
button feature is what I am requesting. It takes you straight to the
code where the actual definition is.
This has been really useful to me when learning Haskell and would also
be useful for beginners who are learning Java. Obviously there would
need to be some kind of link to the source code and making that
linking mechanism is not trivial. Sometimes projects which do not
intend to be open source may not even want that link generated, etc.
There are lots of non-trivial points on what an implementation would
look like.
The linking in the javadoc would not just be useful for people who are
learning java. For those of us, like me, who have been programming
with Java for many years there are lots of times where we want to go
from the javadoc to the actual implementation and we are forced to
find the repo on github and navigate the package structure to get to
the actual class and search for the definition and implementation
there. This would make things simpler.
Please let me know what you think of the idea (total garbage idea,
useful but not priority, etc). I am interested in hearing your
thoughts and responses.
Regards,
Vikram
Vikram,
This is on the low-end of interesting. API documentation is about
providing good quality documentation. It is an admission of failure if
the docs are not sufficient by themselves to document the API, such that
a reader may want to resort to seeing the implementation.
For those learning Java, it would be even worse, allowing people to go
browse the internal details of low-level classes like String.
-- Jon
-- Jon
