Maintenance and refactoring is the main aspect of the Jolt.NET 0.4 release. Prior to this release, I've intentionally delayed many code clean-up tasks as well as performing upgrades of 3rd party dependencies so that I could work on more important features. Now that all those features are complete, I have spent some time to restore the code to its "pristine" state. Here is a summary of the recent updates related to maintenance.
- Updated QuickGraph dependency to QuickGraph 3.3.40824
- Removed FSM->MSAGL conversion code as MSAGL is no longer supported by QuickGraph (superseded by GLEE)
- Removed explicit implementation of equality semantics for Transition class as it is now supported natively by QuickGraph's EquatableEdge type
- Updated RhinoMocks dependency to RhinoMocks 3.6
- Modified relevant unit tests to utilize Act-Arrange-Assert syntax
- Update NUnit dependency to NUnit 2.5.2
- Adopted the use of new constraints to simplify and/or strengthen existing unit tests
- Added additional unit tests to verify presence of attributes on types and their members, a task facilitated by the new constraints in NUnit 2.5
- Unit test maintenance
- Fixed many issues that prevented unit tests from being run in an NUnit project (aggregating many test fixtures)
- Moved much of the reflection code for accessing types and members by strings into separate classes, improving the readability of some unit tests
The following commits introduced new features that were previously planned to be included with the Jolt.NET 0.4 release.
- The Jolt.Convert class will now correctly generate the XML doc comments representation of an explicit or implicit operator
- Predefined .NET operators were already supported
- Consequently, you can now process XML doc comments with a System.Reflection.MethodInfo type referring to an operator
- Created the Jolt.Testing.Assertions.VisualStudio.XmlAssert class to integrate the Jolt XML assertions to the Visual Studio test framework
XML Doc Comment Processing
"Processing the XML File (C# Programming Guide)" describes the supported XML doc comment markup for various types, methods, parameters, and fields. For a given metadata type instance, Jolt.Convert will produce the correct markup, with the exception of the following constructs.
- Function pointer parameter (ELEMENT_TYPE_FNPTR)
- Optional understanding modifier (ELEMENT_TYPE_CMOD_OPT)
- Required understanding modifier (ELEMENT_TYPE_CMOD_REQ)
- Pinned field (ELEMENT_TYPE_PINNED)
- Dimensionless and rank-less array (ELEMENT_TYPE_GENERICARRAY)
In order to verify that my implementation is correct, I compare the output of a .NET compiler with the output of the Jolt.Convert class. Since the C# language does not currently support these constructs directly, other means are required for testing the implementation of the Jolt.Convert class, which are demonstrated below.
To produce XML doc comments with ELEMENT_TYPE_FNPTR, ELEMENT_TYPE_CMOD_OPT, and ELEMENT_TYPE_CMOD_REQ markup, we may use the the C++/CLI compiler to compile the following class.
public ref class XmlDocCommentTest
typedef int (*function_ptr)(char, int, double);
void fnptr(function_ptr f); // ELEMENT_TYPE_FNPTR
void mod_opt(const int n); // ELEMENT_TYPE_CMOD_OPT
void mod_req(volatile int n); // ELEMENT_TYPE_CMOD_REQ
Function pointers are a common construct for C/C++ developers, but understanding why const and volatile translate to optional and required modifiers requires some explanation. Paul DiLascia covers this topic in his article "C++ At Work: Rationales, Highlights, and a Farewell".
ELEMENT_TYPE_PINNED is a bit more tricky since the general C++ literature on pinned pointers states that their usage is restricted to non-static local stack variables, which can not be decorated with XML doc comments. However, the System.Runtime.CompilerServices namespace gives some hints on how discover that a field is pinned. Unfortunately I do not know of a way to verify this behavior using a .NET compiler or other tool.
Finally, ELEMENT_TYPE_GENERICARRAY appears to be deprecated as I can not locate any reference to it in modern .NET documentation (apart from the aforementioned document).
In the mean time, I plan to implement support for all ELEMENT_TYPE_FNPTR, ELEMENT_TYPE_CMOD_OPT, and ELEMENT_TYPE_CMOD_REQ in Jolt.NET 0.4. For ELEMENT_TYPE_PINNED, I will wait until the feature is highly requested or until I stumble upon a tool that will produce the desired output.