From c0298d9f7b17e5532267ba202e06b42b3621af4c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timur=20Sa=C4=9Flam?= Date: Sun, 22 Sep 2024 16:02:07 +0200 Subject: [PATCH] Apply suggestions from code review. --- docs/1.-How-to-Use-JPlag.md | 12 +++++++----- docs/4.-Adding-New-Languages.md | 4 ++-- endtoend-testing/README.md | 10 +++++----- 3 files changed, 14 insertions(+), 12 deletions(-) diff --git a/docs/1.-How-to-Use-JPlag.md b/docs/1.-How-to-Use-JPlag.md index cad4f6fcc..c940816d7 100644 --- a/docs/1.-How-to-Use-JPlag.md +++ b/docs/1.-How-to-Use-JPlag.md @@ -119,13 +119,15 @@ The report will always be zipped unless there is an error during the zipping pro ## Viewing Reports -Starting with version 5.0 the report viewer is bundled in JPlag and can be used locally. This behavior can be controlled with the "--mode" option. -By default, JPlag will process the source files and produce a results.zip. After that the report viewer is started on localhost and the generated report will be shown in your browser. +Starting with version v6.0.0, the report viewer is bundled with JPlag and will be launched automatically. The `--mode` option controls this behavior. +By default, JPlag will process the input files and produce a zipped result file. After that, the report viewer is launched (on localhost), and the report will be shown in your browser. -By specifying "--mode RUN" JPlag will not open the report viewer and only generate the results.zip. -The option "--mode SHOW" will only open the report viewer. You can optionally provide the path to a report file to show immediately show it in the viewer, otherwise the viewer will require you to select a report just like the online version. +The option `--mode show` will only open the report viewer. +This allows you to view existing reports. +You can optionally provide the path to a report file to immediately display it in the viewer; otherwise, the viewer will require you to select a report, just like the online version. +By specifying `--mode run`, JPlag will run but generate the zipped report but will not open the report viewer. -An online version of the viewer is still hosted at: https://jplag.github.io/JPlag/. Drop your `result.zip` folder on the page to start inspecting the results of your JPlag run. Your submissions will neither be uploaded to a server nor stored permanently. They are saved in the application as long as you view them. Once you refresh the page, all information will be erased. +An online version of the viewer is still hosted at https://jplag.github.io/JPlag/ in order to view pre-v6.0.0 reports. Your submissions will neither be uploaded to a server nor stored permanently. They are stored as long as you view them. Once you refresh the page, all information will be erased. ## Basic Concepts diff --git a/docs/4.-Adding-New-Languages.md b/docs/4.-Adding-New-Languages.md index a08ec37fc..5fd6f876c 100644 --- a/docs/4.-Adding-New-Languages.md +++ b/docs/4.-Adding-New-Languages.md @@ -101,8 +101,8 @@ JPlag provides a small framework to make it easier to implement language modules ### Create the Language class -Extends the AbstractAntlrLanguage class and implement all required methods. There are two options for creating the parser. -It can either be passed to the super class in the constructor as shown below or created later by overriding the initializeParser method. +Extends the AbstractAntlrLanguage class and implements all required methods. There are two options for creating the parser. +It can either be passed to the superclass in the constructor, as shown below, or created later by overriding the initializeParser method. The latter option should be used if the parser requires dynamic parameters. ```java diff --git a/endtoend-testing/README.md b/endtoend-testing/README.md index ea10277e4..f27e7019d 100644 --- a/endtoend-testing/README.md +++ b/endtoend-testing/README.md @@ -1,14 +1,14 @@ # JPlag - End-To-End Testing -The end-to-end test module contains test that report any chance in the similarities reported by JPlag. +The end-to-end test module contains tests that report any chance in the similarities reported by JPlag. There are two kinds of tests: 1. Simple tests that fail if the similarity between two submissions changed 2. Gold standard tests ## Gold standard tests -A gold standard tests serves as a metric for the change in detection quality. It needs a list of plagiarisms in the data set. -The comparisons outputted by JPlag are split into comparisons that should be reported as plagiarisms and comparisons that shouldn't. +A gold standard test serves as a metric for the change in detection quality. It needs a list of plagiarism instances in the data set. +JPlag outputs comparisons split into those that should be reported as plagiarism and those that shouldn't. The test will fail if the average similarity on one of those groups changed. In contrast to the other kind of test, this offers a rough way to check if the changes made JPlag better or worse. ## Updating tests @@ -25,9 +25,9 @@ This segment explains the steps for adding new test data New test data can be obtained in multiple ways. -Ideally real world data is used. To use gold standard tests real world data needs to contain information about which submission pairs are plagiarism and which aren't. +Ideally, real-world data is used. To use gold standard tests, real-world data needs to contain information about which submission pairs are plagiarism and which aren't. -Alternatively test data can be generated using various methods. One such method is explained below. +Alternatively, test data can be generated using various methods. One such method is explained below. The test data should be placed under [data](src/test/resources/data). It can either be added as a directory containing submissions or as a zip file.