Feature request: link to source from javadoc

[Jonathan Gibbons]

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