Document `Datatables`

[rpau]

At this moment there are some important recipes that use datatables, which is an interesting structure to aggregate data in the Moderne platform.

There is no documentation yet about datatables, which should be a basic OpenRewrite concept.

[okundzich]

We need also to improve the recipe documentation generator so that we can see which datatables a recipe produces.

[mike-solomon]

I haven't worked with data tables before so will definitely need some assistance from someone else to get a doc added and the markdown generator updated.

Happy to clean up or write the doc if I get some more information, though.

[mike-solomon]

I started looking into this but it sounds like this feature is only half finished right now. If you make a recipe with a data table and run it locally, you can't actually access or see that table as other plugins haven't been updated. Furthermore, it sounds like testing for the data tables hasn't been fleshed out yet.

I plan on waiting until those things are resolved before working on this issue.

[mike-solomon]

To save some of my notes for the future:

When making a Data Table you'll need to:

1. Create a class that extends DataTable<Row>
2. The Row class is typically defined as a static class inside of your DataTable class.
3. Rows have @Column annotated variables. Each column should have a displayName and a description.

Example Data Table Class:

public class NameOfTable extends DataTable<NameOfTable.Row> {
    public NameOfTale(Recipe recipe) {
        super (recipe,
                "Display name of table",
                "A detailed description of the table."
        )
    }

    @Value
    public static class Row {
        @Column(displayName = "Some name", 
                description = "Some description.")
        String someColumn;

        @Column(displayName = "A different display name", 
                description = "A different description.")
        Long someOtherColumn;
    }
} 

• Example recipe
• Example test that will change

Questions:

1. For a DataTable Row, are there any restrictions on the columns?
2. Why would someone use the constructor that specifies the row type and row name? It seems like every example I find just adds in Row.class and ClassName.class.getName() which doesn't feel useful compared to the more generic constructor.

[mike-solomon]

related issue for the markdown generator: https://github.com/openrewrite/rewrite-recipe-markdown-generator/issues/57

[timtebeek]

Adding a link here for folks already interested in data tables, as those have been documented for users of Moderne: https://docs.moderne.io/user-documentation/data-tables The Moderne CLI, which runs OpenRewrite recipes, also already produces data tables, as used in mod study.

Documentation of data tables for OpenRewrite will make sense as soon as we have support in each of the plugins for producing data tables as well, likely using the same format as used in the CLI:

• https://github.com/openrewrite/rewrite-gradle-plugin/issues/201
• https://github.com/openrewrite/rewrite-maven-plugin/issues/555

[mike-solomon]

As data tables appear to be more of a moderne feature and there are no plans to update OpenRewrite recipe output to see and use data tables, I'm going to go ahead and close this issue. If that changes in the future, we can explore adding this to the docs.