During our last online session on March 25th there was a dicsussion about how we make it easier for people to migrate their applications to X# and how to document the common pitfalls and other problems. People suggested that they would want to help out with for example documenting compiler errors with examples of code that throws these errors and examples of how to solve these problems.
In this article we would like to list several areas of the XSharp project where we could use some help
| Area | Description | What can you do |
| Compiler errors | Most of the X# compiler errors list the error / warning number, but do not have examples of code where the error occurs and do not have examples of how to solve the problem. This is partially caused by the fact that we have "inherited" these errors and warnings from Roslyn. |
When you encounter an error that is not documented, then you create a document with an example of the code that failes and how to solve it. An example of a Help page that is partially done is: https://www.xsharp.eu/help/xs0246.html This was based on the C# compiler help page But as you can see: the examples have not been included. This example shows:
|
| Runtime Documentation | The X# runtime documentation is partially "lifted" from the Visual Objects and FoxPro documentation. Not all topics have example code and the example code is not always "up to date" or correct | Create examples and check for correctness of the current documentation. The current documentation consists partially of "inline" documentation and partially of external XML files with pieces of documentation that are referred to from within out code. If you look at https://github.com/X-Sharp/XSharpPublic/blob/main/Runtime/XSharp.RT/Functions/Date.prg then you will see that the documentation comment in this file for the Bin2Date() function links to an external file: /// <include file="VoFunctionDocs.xml" path="Runtimefunctions/bin2date/*" /> The documentation for the function is in the external file in the section <bin2date> .. </bin2date> If you have an example that demonstrates more that one function or more than one method, then this example can also be placed in a shared file and can be linked to the topics just like the comment about static memory, so the example will not be duplicated in the source. |
| Validate or review the code | The X# source code is all on Github. We have done our best to create code that is understandable and works without issues. For a part of the code we have also created unit tests to make sure that it is tested when the compiler or runtime is changed. | We could use extra eyes that look over the code and check for problems. It is especially important that "edge cases" (boundary values) and undocumented behavior from the original languages are checked and found to be working and converted to unit tests. For example, given a decimal comma,which value should the be returned from the Val() function if you pass it the string "1.234" . And when the date format is DD-MM-YYYY what should CtoD() return for the string "01.01.2021" (should it ignore the separaors) and what for "01.31.2021" (should it be "smart" and understand that 31 cannot be the month, so it should be the date. For examples of unit tests please look at https://github.com/X-Sharp/XSharpPublic/blob/main/Runtime/XSharp.Core.Tests/ConversionTests.prg#L27. We are using XUnit for our testing. |
| Test Data | Our RDD system reads the original codepage from the DBFs based on known tables. We do NOT however have example code for codepages that are unfamiliar to us, such as the Multi Byte codepages (Japanese, Korean etc) | If you are a developer from a country with a non standard codepage, please create test dbf data and and let us know what it should look like and the order in which the data must be sorted . Creating an index with YOUR collation and documenting how that needs to be ordered will help us to make sure that we are handling your codepages and collation correctly. |
| Write Code | We have not completed writing all of the runtime code to support all dialects. | If you want to help writing missing runtime functions then you are more than welcome. |
How do you want 1+2 delivered? I can for example send you a few Help nDoc pages (I own it too but I haven't updated it for a while , I am on version 5) for a currently undocumented errors in the way you describe above, so you can check if it meets your expectation. Is that a good idea?
Dick
We use Help and Manual (I think that is a different product than HelpnDoc).
So to void compatibility issues I would prefer Html, Word, Text.
Robert