Bring back SwingBuilder widgets list

[kriegaex]

While Codehaus was still hosting the Groovy documentation, there was an alphabetical widgets list for the SwingBuilder DSL plus detail pages, e.g. for tabbedPane. Now, I can only find those pages on archive.org. Please bring that lost part of the documentation back into the main Groovy documentation. It is super difficult to discover the available widgets and their paramateters from an IDE, especialls for developers who are not Swing buffs already. IntelliSense in my IDE does not help much there. SwingBuilder is still available in a Groovy module even in Groovy 4, so it would make sense to documents it, too.

[paulk-asert]

I think that page was always getting out of date and we had hoped to generate it manually somehow but up until now haven't achieved that. The workaround is to look for all the registerFactory and registerBeanFactory method calls within the SwingBuilder source file. An automatically generated file would be missing the helpful "Notes" column but would at least be a start. In reality, this file hasn't changed much in recent times, so generating it isn't as crucial as it might have once been.

[kriegaex]

@paulk-asert, so what is your plan? I cannot say anything intelligent about how difficult it would be to generate those pages and keep them up to date. I just know that presently, I have no clue how to use those Swing builder classes and discoverability in my IDE is close to zero. Looking at the Swing builder source code is not such an appealing option. If your goal is to auto-generate the documentation, I guess it would make sense for it to live in the source code. Maybe there even is a way to put the notes there for the hypothetical generator to discover.

[paulk-asert]

The plan is to provide the info you are after, but like all things in an open source community project, it will happen when someone in the community finds the time. I hope to take a look myself sometime in the coming weeks but someone else might beat me to it.

[jagedn]

I'm using Intellij and I can see autocompletion for all of them

[kriegaex]

@jagedn, yeah, I know they are there, but I was talking about discoverability. If I already know what I am searching for and start typing a widget name, I can spot them. Otherwise, just pressing Ctrl+Space, I see an overwhelming number of options - constants, Groovy API etc. - and can scroll down the list for minutes. Also, even if I find what I want, Ctrl-Q does not show any helpful documentation:

Well, yeah, so now I know that all those methods have java.util.Map attributes arguments lists.

Then, inside an arguments list, it is similar. If I just want to see which options there are at all via Ctrl+Space, I need to spot the ones with a trailing colon while scrolling the list. This is all feasible, but not very nice. Maybe I should rather blame the IDE or my lack of knowledge about how to optimally configure IntelliSense in IntelliJ IDEA, but it does not make things easier. The named parameters also have no documentation I could open with Ctrl-Q:

This is why I opened this issue in order to bring back some helpful, old-school API description for all widgets and their options into the Groovy documentation. If widget, option and especially documentation (Javadoc, Groovydoc) discoverability in my IDE was adequate, I would maybe not need that. But for now, I do.

[paulk-asert]

Check out this PR for a solution (it uses a script to generate the doco):

apache/groovy#2450

This is within the Groovy doco itself (we tend to have version agnostic content here and version specific content within the groovy project itself). That way if SwingBuilder is tweaked to support different things in different versions, we can regenerate.

The content ends up in the domain specific languages part of the guide which is where SwingBuilder itself is.

[kriegaex]

@paulk-asert, thanks for taking care of this. I am not going to review the PR as such. However, feel free to let me know where to browse and review documentation content generated by that script. You do not need my thumbs up, but as the creator of this issue I want to provide some feedback to show my appreciation and do my humble part of the job.

[paulk-asert]

Sorry for the delay. You can find the list at:

https://docs.groovy-lang.org/docs/latest6/html/documentation/core-domain-specific-languages.html#swing-builder-widgets

I am expecting the "latest6" part won't be needed once 6 is released.

[kriegaex]

@paulk-asert Thank you, I am just now taking a cursory glance at the new auto-generated docs, dropping a few notes here while I am looking into tabbedPane, because it is what I used as an example to point to the old docs found at archive.org:

• There is a lot of information about widgets and attributes, which is good.
• The first thing I noticed is a broken link to the Java API docs:
  • The link is https://docs.oracle.com/en/java/javase/17/docs/api/index.html?javax/swing/JTabbedPane.html,
  • but should be https://docs.oracle.com/en/java/javase/17/docs/api/java.desktop/javax/swing/JTabbedPane.html.
• The properties list makes no difference between properties specific to the class and inherited ones. It would be nice to have them grouped, listing more specific ones first and those further up the hierarchy last.
• The "Readable" and "Writable" columns in the table are empty, which looks like a bug and rather creates confusion for the reader than helping her.
• The class names in the "Type" column of the table are not linked to their respective Java API docs pages.
• There is no sample code like in the old documentation.
• There is no clue concerning which other elements - e.g. panel, label - can be embedded in the documented widget.

While it is probably not straightforward to auto-generate example code (even though I could envision such a thing), all other issues listed above should be able to be auto-generated.

P.S.: Was it a good idea to close the issue without waiting for some user feedback first?

[paulk-asert]

Other folks have been using the docs since April but possibly not extensively, and hadn't commented on the flaws. I'll re-open for now.

[kriegaex]

Thank you very much, @paulk-asert. It is entirely possible that there are a few more glitches. I really just took a brief glance, no more than 5 minutes.

[paulk-asert]

Try this:
https://docs.groovy-lang.org/docs/groovy-7.0.0-SNAPSHOT/html/documentation/core-domain-specific-languages.html#swing-builder-widgets