Maybe https://javacc.github.io/javacc/documentation/jjdoc.html would work. We probably just need to extend the grammar file with a bit of meta information (like when added, related JIRA)
> On 12. Feb 2021, at 15:32, Bertrand Delacretaz <[email protected]> wrote: > > Hi Konrad, > > On Fri, Feb 12, 2021 at 3:18 PM Konrad Windszus <[email protected]> wrote: >> ...in some cases instructions have been extended, e.g. >> 1) intermediate path support for user creation >> (https://issues.apache.org/jira/browse/SLING-7226) >> 2) forced intermediate path support for user creation >> (https://issues.apache.org/jira/browse/SLING-9857) ... > > Granted, this warrants better documentation. > >> ...For me it would be good to have a list of instructions which contains the >> following data per instruction: >> - The syntax of the instruction (clearly indicating which directives are >> required vs. which are optional, e.g. "path" directive for "create user" is >> optional. >> - A short description what it does. >> - Related JIRA ticket (multiple ones possible) >> - Repoinit language version, repoinit parser version and jcr.repoinit >> version ... > > I agree, but can we find a way to generate that from the grammar file > along with its history? Maybe adding some "doc comments" in that file. > > Worst case, or as a starting point, we might document how to read that > grammar file? I think it's pretty readable if you know where to look, > for example: > > void createUserStatement(List<Operation> result) : > { > /* this section can be ignored, implementation details */ > Token user = null; > Token encoding = null; > Token password = null; > WithPathOptions wpopt = null; > } > { > /* this is the actual CREATE USER grammar */ > <CREATE> <USER> > ( user = <STRING> ) > ( wpopt = withPathStatement() ) ? > ( <WITH> <PASSWORD> ( <LCURLY> encoding = <STRING> <RCURLY> )? > password = <STRING> )? > > /* implementation details again */ > { > result.add(new CreateUser(user.image, > (encoding == null ? null : encoding.image), > (password == null ? null : password.image), > wpopt > )); > } > } > > I think writing an explanation of how to read that file could be a > good start? The github tags say what's in which version of the parser. > > To go further, there's probably a tool to document javacc grammars, I > haven't had time to look right now. Or we grab the javacc language > grammar and write a conversion tool to a more readable format, for > example just omitting the "can be ignored" sections above. > > My angle is that unless these docs are generated automatically (or we > train people to read the grammar), docs are likely to get out of > sync... > > -Bertrand > > [1] > https://github.com/apache/sling-org-apache-sling-repoinit-parser/blob/master/src/main/javacc/RepoInitGrammar.jjt
