diff --git a/doc/sphinx/user_manual/installation/included.md b/doc/sphinx/user_manual/installation/included.md index d59b11bca..4481a42af 100644 --- a/doc/sphinx/user_manual/installation/included.md +++ b/doc/sphinx/user_manual/installation/included.md @@ -15,8 +15,8 @@ It also contains the wrapper code to interface with C, Python, and Fortran progr The World Builder app --------------------- -This is a program which can be used to query the World Builder from the command line, by providing it a world builder file, and then a data file. -This data file should contain in the header information on the dimension you want to use and the amount of compositions, and in the main part, the required information (for example, for a 3d case: x, y, and z; position, depth, and gravity). +This is a program which can be used to query the World Builder from the command line, by providing it a World Builder file, and then a data file. +This data file should contain in the header information on the dimension you want to use and the number of compositions, and in the main part, the required information (for example, for a 3d case: x, y, and z; position, depth, and gravity). It then outputs a file with these properties, and the temperature and compositional values behind them. For more information on how to use the World Builder app see {ref}`part:user_manual:chap:how_to_use_the_apps:sec:gwb-dat_app`. @@ -37,23 +37,23 @@ We currently have two types of tests implemented. The first, and currently the most important one, is the unit tester. This tester allows testing of individual functions of the World Builder library in relative isolation. The second type of tester is an integration tester, which works through the World Builder app. -This tester tests whether the whole library works in the expected way it is supposed to by providing a World Builder file and data points to get temperature and composition from them. +This tester tests whether the whole library works as expected by providing a World Builder file and data points to obtain temperature and composition. The tester package is run every time on proposed new code before that code is added to the main World Builder repository, and all tests have to pass before the code can be merged. This happens through GitHub actions (see ) and AppVeyor (see ). Having tests alone is not good enough to make sure that the World Builder actually does what it is supposed to do. -The tester should theoretically cover all the possible cases which a software package can provide. +The tester should theoretically cover all the possible use cases. In practice we test the coverage by counting the number of 'relevant' lines and how many of these lines are touched when running the tester. This is counted and reported by the program Gcov (). This approach is not perfect and has two main problems. -The first problem is that a 100% coverage is practically not achievable, since the code might have fail assertions in places which should never be reached. +The first problem is that a 100% coverage is practically not achievable since the code might have fail assertions in places which should never be reached. The second problem is that even though a line of code is touched by the tester, it may not mean that all possible cases in that line are tested. Think for example of an inline if statement, or an assertion macro lines. -These lines count as being touched by the tester, but only one case may actually be tested. +These lines count as being touched by the tester but only one case may actually be tested. As long as these limits are kept in mind, there is no problem in using this kind of coverage to test the tester quality. -Keeping these limits in mind, we try to keep the code above 95% coverage. +With this limitation, we try to keep the code above 95% coverage. At the time of writing, the coverage is above 98%. The coverage is measured and reported every time when new code is proposed. This happens through Coveralls (see ).