Publish Javadoc to well-known location

[sbrannen]

The Spring Framework build has recently started reporting the following warning.

warning: URL https://eclipse.dev/aspectj/doc/released/aspectj5rt-api/element-list was redirected to https://projects.eclipse.org/projects/tools.aspectj

However, https://projects.eclipse.org/projects/tools.aspectj is not the location for the AspectJ Javadoc.

I apologize if I have overlooked something, but I cannot determine where the AspectJ Javadoc is currently published online.

Can you please update the project's README to point to the location where AspectJ's Javadoc is published?

For example, Spring Framework would currently need to link to the Javadoc for AspectJ 1.9.22.1.

[kriegaex]

@aclement, you have not reacted to my latest e-mail about the PHP migration f***-up which made the complete AspectJ docs (of which the javadocs are but a small part) become unaccessible due to faulty redirection. You told the Eclipse admin team how you wanted it done. Maybe, you can coordinate with them to fix it again. You know that I am on hiatus until I found a sponsor. Thank you very much.

[kriegaex]

@sbrannen, it looks as if the issue is resolved and the AspectJ documentation accessible again right from the same URLs it used to be before Eclipse deactivated PHP on its pages and a glitch happened with redirection while someone tried to work around it.

When opening https://projects.eclipse.org/projects/tools.aspectj, you find a link named "Website", leading to https://eclipse.dev/aspectj/, which is now accessible again without falsely linking back to the project page. There, you find a link "Docs", leading to https://eclipse.dev/aspectj/doc/latest/index.html. Finally, there you find links to javadocs:

• https://eclipse.dev/aspectj/doc/latest/runtime-api/index.html
• https://eclipse.dev/aspectj/doc/latest/weaver-api/index.html

The credit for fixing the problem goes to @aclement. 🙏

[kriegaex]

Reopening because the read-me needs an update. It currently contains only GitHub links, but the javadocs are published separately and cannot be accessed inline from GitHub. Links to the Eclipse project page, the AspectJ website and specifically to the docs overview page should be part of the read-me.

[sbrannen]

When opening projects.eclipse.org/projects/tools.aspectj, you find a link named "Website", leading to eclipse.dev/aspectj, which is now accessible again without falsely linking back to the project page. There, you find a link "Docs", leading to eclipse.dev/aspectj/doc/latest/index.html. Finally, there you find links to javadocs:

Thanks for the details on how to navigate through all of that. Much appreciated. Plus, I discovered the AspectJ Java version compatibility page which is handy.

And thanks for updating the GitHub README as well. 👍

The credit for fixing the problem goes to @aclement. 🙏

Indeed it does! Cheers, @aclement. 👏

FYI: Andy has also published modern Javadoc for AspectJ Runtime types here: https://eclipse.dev/aspectj/doc/released/1.9.22.1/aspectjrt/.

See also: spring-projects/spring-framework#34293

[kriegaex]

FYI: Andy has also published modern Javadoc for AspectJ Runtime types here: https://eclipse.dev/aspectj/doc/released/1.9.22.1/aspectjrt/.

Sorry, but what about it is different from the https://eclipse.dev/aspectj/doc/latest/runtime-api/ I published long ago? At first glance, it looks identical. Please enlighten me.

[sbrannen]

Sorry, but what about it is different from the eclipse.dev/aspectj/doc/latest/runtime-api I published long ago? At first glance, it looks identical. Please enlighten me.

As I mentioned in spring-projects/spring-framework#34293, the old Javadoc was for AspectJ 1.6 (2009).

The Javadoc is very different: different style, search box, element-list file instead of package-list file, and it's based on AspectJ 1.9.22.1.

[kriegaex]

@sbrannen Again: I published it long ago like this, your links simply used the old location with the legacy docs that I kept around for a while so as not to disrupt people using old links too much too quickly. The link to the element list you just used is from the version I published. It also has the search box. IMO it was completely unnecessary and redundant to publish it one more time. Just update the link and be happy. Did you compare the two aspectjrt javadocs? What is different about them?

@aclement Can you maybe explain why you re-published something that was already published and linked off of the docs overview page (see my screenshot above) for a long time?

[kriegaex]

To be exact, I added the modern javadocs for both weaver and runtime on Valentine's Day 2024, i.e. almost a year ago, see e.g. this Git file history. Last time I updated everything for 1.9.21.1, since then there have not been any changes in API docs AFAIR, so updates for 1.9.22 or 1.9.22.1 were unnecessary.

[sbrannen]

I published it long ago like this,

I was not aware of what had been published, where, when, or by whom.

your links simply used the old location with the legacy docs that I kept around for a while so as not to disrupt people using old links too much too quickly.

Makes sense to keep the old stuff around with the package-list files, but I assume many people were not aware that there were new locations for AspectJ's Javadoc.

For the Spring Framework, I assume the external link to AspectJ's Javadoc had been configured once and remained in the build, unchanged, for years.

The link to the element list you just used is from the version I published. It also has the search box. IMO it was completely unnecessary and redundant to publish it one more time.

If the content is identical, there is of course no reason to publish two identical "latest" Javadoc sites.

But having a latest/current publication as well as publications for individual versions can be beneficial if one wants or needs to reference a particular version.

In any case, it would be very beneficial if the AspectJ Javadoc contained the AspectJ version.

For example, the latest runtime docs could be called "AspectJ Runtime 1.9.22.1 API" instead of just "AspectJ Runtime API", analogous to how the current Spring Framework docs are called "Spring Framework 6.2.2 API".

Just update the link and be happy.

If the https://eclipse.dev/aspectj/doc/latest/runtime-api/ site is guaranteed to be stable, that is likely what we will do for the Spring Framework build.

Did you compare the two aspectjrt javadocs? What is different about them?

I honestly have no idea about the structure of the filesystem on the web server that hosts the AspectJ content. So I don't know who published what or when; I don't know which directories are symbolic links; etc.

So I'll leave it up to the AssertJ maintainers to sort that out.

[aclement]

@aclement Can you maybe explain why you re-published something
I wasn't aware or had forgotten.

[kriegaex]

No problem, @aclement, that is why I commented. Now we are all on the same page, which is great. 🙂

I suggest you simply revert eclipse-aspectj/aspectj-website@4c5a244.

[kriegaex]

@sbrannen

Makes sense to keep the old stuff around with the package-list files

It was fine for a while, but actually I intended to remove the legacy stuff a few months ago, around the time I decided to go on hiatus, and finally forgot to do it. That is the only reason the old documentation is still on the website. I actually want it to break, so as to encourage users and projects to use the current docs in modern layout - not just javadocs but also Asciidoc-based user and developer docs.

but I assume many people were not aware that there were new locations for AspectJ's Javadoc.

For most people, probably this was not a problem, because they do not use permanent links to it but find it via the project website and the docs overview page (where the links to the old docs have been replaced by ones to the new ones long ago) or even just read API docs in their respective IDEs. Spring's use case is rare, but of course valid.

For the Spring Framework, I assume the external link to AspectJ's Javadoc had been configured once and remained in the build, unchanged, for years.

Yes, no problem. Had I been more consequent to delete the old docs completely, this would have broken long ago. As the redirection glitch proves, unavailability made you aware of the change, albeit indirectly in this case. 😉

In any case, it would be very beneficial if the AspectJ Javadoc contained the AspectJ version.

I made the decision on purpose to not publish APi docs per release but only the latest, as was always the practice even before I started contributing to the problem. But I am not simply continuing an old practice but decided like this simply due to that fact that for the last couple of years I was the sole maintainer of AspectJ, its website, AJDT, AspectJ JDT Core, AspectJ.dev AspectJ Maven Plugin and a few other projects. I also added build steps to strip off some content like timestamps and version numbers from the javadocs to keep the commit diffs small and readable, because I like it that way. I would like to be able to diff javadocs just like normal code and mostly just see changes in content, not in structure or metadata.

If the https://eclipse.dev/aspectj/doc/latest/runtime-api/ site is guaranteed to be stable, that is likely what we will do for the Spring Framework build.

That was/is indeed the plan.

I'll leave it up to the AssertJ maintainers to sort that out.

AspectJ, please. AssertJ is a different beast. 😉

[lefou]

A project version number is essential in a documentation. A user has no other way to know, which exact version is documented. Of course, timestamps and used tools versions can be stripped since they make built artifacts non-reproducible.

[sbrannen]

For most people, probably this was not a problem, because they do not use permanent links to it but find it via the project website and the docs overview page (where the links to the old docs have been replaced by ones to the new ones long ago) or even just read API docs in their respective IDEs. Spring's use case is rare, but of course valid.

Indeed. There probably are not that many projects which publish their Javadoc containing links to AspectJ's javadoc. I suppose most projects just use AspectJ without explicitly referencing AspectJ types in their Javadoc.

For the Spring Framework, I assume the external link to AspectJ's Javadoc had been configured once and remained in the build, unchanged, for years.

Yes, no problem. Had I been more consequent to delete the old docs completely, this would have broken long ago. As the redirection glitch proves, unavailability made you aware of the change, albeit indirectly in this case. 😉

Exactly

In any case, it would be very beneficial if the AspectJ Javadoc contained the AspectJ version.

I made the decision on purpose to not publish APi docs per release but only the latest, as was always the practice even before I started contributing to the problem. [...] I also added build steps to strip off some content like timestamps and version numbers from the javadocs to keep the commit diffs small and readable, because I like it that way. I would like to be able to diff javadocs just like normal code and mostly just see changes in content, not in structure or metadata.

I think those other changes you made are fine, and it's also fine just to publish the "latest and greatest" under the latest directory.

However, I still think it would benefit the community if the latest Javadocs referenced the AspectJ API version included in those docs. And I don't think that would make diffs unmanageable.

If the eclipse.dev/aspectj/doc/latest/runtime-api site is guaranteed to be stable, that is likely what we will do for the Spring Framework build.

That was/is indeed the plan.

Thanks for the confirmation.

I just updated Spring Framework's build accordingly: spring-projects/spring-framework@683733a

I'll leave it up to the AssertJ maintainers to sort that out.

AspectJ, please. AssertJ is a different beast. 😉

Oh nooooooo.... Can't believe I typed "AssertJ". 🤦

But, to be honest, that's not the first time my brain has switched up AspectJ and AssertJ, AOT and AOP, etc. 😉