Contributing - accord-net/framework GitHub Wiki

You would like to contribute to the project, amazing! Thanks a lot in complete advance whether end up contributing or not! To be interested in contributing is already an amazing huge step, and there are many ways you can contribute, hopefully one of them will fall under your domain.

Please open an issue in the project's issue tracker documenting the feature you would like to contribute and why you think it would be useful to the framework. When submitting your contribution, please be sure to agree to license it under the MIT, BSD or LGPLv2.1 licenses, in this order of preference.

In the past year, the large majority of issue requests opened in the framework issue tracker were related to documentation examples. As such, the most important thing the reader could possibly contribute right now is a new example about how something could be done using Accord.NET.

However, one important thing to note here is that actually, most of the examples that people ask in the issue tracker are about things that are (1) already available and (2) that actually already have examples showing how they could be used!

The problem is that those examples referred in item (2) above are not in the official project documentation but rather available inside unit tests inside the framework's Unit Test projects. As such, in the majority of cases, contributing a new documentation example to the project's documentation should not involve writing any new lines of code but rather locate where an example can be found in the project's unit tests and "re-frame" it as a documentation example. More details will be given below.

Right now, the list of open documentation issues can be found at this link. By clicking this link, you should be able to see a filtered version of the project's issue tracker considering only documentation request issues which have not yet been answered. You can select any issue among those to start working on, so please be sure to select one that happens to fall under a topic you believe you might be able to help.

• Please make sure you have actually been able to clone the project, build it, and execute the project's unit tests. The project can be cloned from https://github.com/accord-net/framework. In order to build it, you can follow the instructions at https://github.com/accord-net/framework#building (if you are new to the project, please use VS2017 community to make things easier for you). Finally, be sure you can run the project's unit tests (using the NUnit 3 Test Adapter) so that you can navigate and test easily the unit tests already present in the framework.

1. Navigate to the project's issue tracker, and use the following filter: is:issue is:open label:"doc request" -label:"pending-release" or click this link to open the filtered issue list directly;
2. Choose an open issue, such as, for example, Issue 455
3. Find examples of how this method can be used in the project's unit tests. If such example already exists in the unit tests, adapt it into a code example as will be explained below. If you cannot find this unit test, you can either write one and then proceed as described below, or look for a new documentation request issue to be solved.

The first step into creating a new documentation example would be to find a unit test that already gives an example about how some feature needs to be used but has not made into the official documentation yet. For example, let's consider the Distance.Euclideanexample below (given in Issue #455). Firstly, find the Distance.Euclidean method in the framework. This can be done by opening up Visual Studio and looking for Distance.Euclidean in the Solution search box as shown below:

According to the issue description, this is the method we would need to be documenting:

Now, let's search for places where this method has actually been called by right-clicking "Find all references" as shown below.

You will arrive at the following method:

which is also reproduced below:

        /// <summary>
        ///   Gets the Euclidean distance between two points.
        /// </summary>
        ///  
        /// <param name="vector1x"></param>
        /// <param name="vector1y"></param>
        /// <param name="vector2x"></param>
        /// <param name="vector2y"></param>
        /// 
        /// <returns>The Euclidean distance between x and y.</returns>
        /// 
#if NET45 || NET46 || NET462 || NETSTANDARD2_0
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
#endif
        public static double Euclidean(double vector1x, double vector1y, double vector2x, double vector2y)
        {
            // Note: this is an auto-generated method stub that forwards the call
            // to the actual implementation, indicated in the next line below:
            return cacheEuclidean.Distance(vector1x, vector1y, vector2x, vector2y);
        }

Ok, this method is still not under the unit tests of the framework. But note the comment: this method is just a forward pass from an auto-generated class. Let's do the same operation and right click the method name and select "Find all references":

This time, we have been able to reach an unit test where this feature has actually been used:

The source code for the unit test is reproduced below:

        [Test]
        public void EuclideanTest1()
        {
            double x1 = 1.5;
            double y1 = -2.1;

            double x2 = 4;
            double y2 = 1;

            double actual = Distance.Euclidean(x1, y1, x2, y2);

            Assert.AreEqual(3.9824615503479754, actual, 1e-10);
            Assert.IsFalse(double.IsNaN(actual));
        }

Now, in order to convert this test into a documentation example, all we have to do is to add some introductory comments and encapsulate the example with #region guards:

        [Test]
        public void EuclideanTest1()
        {
            #region doc_euclidean 
            // Declare coordinates of the first point
            double x1 = 1.5;
            double y1 = -2.1;

	    // Declare coordinates of the second point
            double x2 = 4;
            double y2 = 1;

            // Compute the distance betwen the first and second points:
            double actual = Distance.Euclidean(x1, y1, x2, y2); // output should be 3.9824615503479754
            #endregion
			
            Assert.AreEqual(3.9824615503479754, actual, 1e-10);
            Assert.IsFalse(double.IsNaN(actual));
        }

This should become:

As you can see, be sure to:

• Put the Assert lines outside of the example region;
• Add comments for any produced result (such as the expected distance in this case)

Now, let's go back to the original method implementation we were trying to document. This will send us here:

Reproduced again below:

        /// <summary>
        ///   Gets the Euclidean distance between two points. Note: this function 
        ///   is dangerous as it is too easy to invert its arguments by mistake. 
        ///   Please consider using the Tuple&lt;double, double> overload instead.
        /// </summary>
        /// 
        /// <param name="vector1x">The first coordinate of first point in space.</param>
        /// <param name="vector1y">The second coordinate of first point in space.</param>
        /// <param name="vector2x">The first coordinate of second point in space.</param>
        /// <param name="vector2y">The second coordinate of second point in space.</param>
        /// 
        /// <returns>The Euclidean distance between x and y.</returns>
        /// 
#if NET45 || NET46 || NET462 || NETSTANDARD2_0
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
#endif
        public double Distance(double vector1x, double vector1y, double vector2x, double vector2y)
        {
            double dx = vector1x - vector2x;
            double dy = vector1y - vector2y;
            return Math.Sqrt(dx * dx + dy * dy);
        }

Now, in order to add our example to the documentation, we just have to add the following code to its XML documentation:

        /// <example>
        /// <code source="Unit Tests\Accord.Tests.Math\DistanceTest.cs" region="doc_euclidean" />
        /// </example>

The final XML documentation should then look like

        /// <summary>
        ///   Gets the Euclidean distance between two points. Note: this function 
        ///   is dangerous as it is too easy to invert its arguments by mistake. 
        ///   Please consider using the Tuple&lt;double, double> overload instead.
        /// </summary>
        /// 
        /// <example>
        /// <code source="Unit Tests\Accord.Tests.Math\DistanceTest.cs" region="doc_euclidean" />
        /// </example>
        /// 
        /// <param name="vector1x">The first coordinate of first point in space.</param>
        /// <param name="vector1y">The second coordinate of first point in space.</param>
        /// <param name="vector2x">The first coordinate of second point in space.</param>
        /// <param name="vector2y">The second coordinate of second point in space.</param>
        /// 
        /// <returns>The Euclidean distance between x and y.</returns>
        /// 
#if NET45 || NET46 || NET462 || NETSTANDARD2_0
        [MethodImpl(MethodImplOptions.AggressiveInlining)]
#endif
        public double Distance(double vector1x, double vector1y, double vector2x, double vector2y)
        {
            double dx = vector1x - vector2x;
            double dy = vector1y - vector2y;
            return Math.Sqrt(dx * dx + dy * dy);
        }

The final version of the method should be:

After that, the code example should be able to be automatically picked by the documentation project and will be included in the next time the documentation is rebuilt.