Documentation Language Modules

[JanWittler]

Referenced files:
https://github.com/robinmaisch/JPlag/tree/master-remote/docs/frontend-design

This issue is used to collect and discuss feedback regarding the documentation of the language frontends.

Relates to #345.
@robinmaisch @jplag/maintainer

[JanWittler]

Overall looks good to me.

FrontendDesign.md

--

FrontendStructure.md

Not much to complain about here neither. The tables are a bit hard to read as they are so close by each other but have different column widths.

TokenExtraction.md

• Maybe drop approach 3?

TokenSelection.md

• I would disagree that readability is a necessary property of the token extraction. The tokens should have a debug description but one does not have to optimise the token set for readability.
• Also I wouldn't say it has to be consistent with other language frontends. If we detect empirically that some tokens should always be extracted, we can require this as a baseline, but languages can differ fundamentally which even may make it impossible for tokens to be consistent (e.g. Haskell doesn't have loops)
• Tip 2 is written a bit confusing.
• Tip 5 code example is a bit confusing without any reference code.

[robinmaisch]

Sorry for the long delay. Before I push another version, just a few questions back to you:

• I see your point about the readability. Should I reframe it as a 'nice to have' feature that will aid the design process, or cut it altogether? I realize, what I really meant by 'readable tokens' is to choose readable String representations for them.

• Also about the consistency, should I try to emphasize the limitations to that point that come with different programming paradigms, or leave it out? Using the experience from existing frontends that we know to work well – to the extent possible – surely is not an absolute requirement, but it did play a major role for my contribution.

[JanWittler]

I see your point about the readability. Should I reframe it as a 'nice to have' feature that will aid the design process, or cut it altogether? I realize, what I really meant by 'readable tokens' is to choose readable String representations for them.

No hard opinions regarding this. As the String representations are enforced anyways by the interface specifications, I don't see the necessity to document this here additionally.

Also about the consistency, should I try to emphasize the limitations to that point that come with different programming paradigms, or leave it out? Using the experience from existing frontends that we know to work well – to the extent possible – surely is not an absolute requirement, but it did play a major role for my contribution.

I agree, so I would go with your first mentioned option, i.e. suggest to reuse knowledge from existing frontends if the language paradigms match to some extent.

[robinmaisch]

Thanks for the feedback! The docs files are updated now.

[tsaglam]

✅ Documentation incorporated into the wiki and the repo!