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.