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
