Document ConfigurationContainer, Type, and Member Extension Methods

I’m really enjoying this library, and I’ve been using it with not too much effort in my current Windows Forms app I’m making for my self-teachings in VB.NET.

However, it took me a while to realize how this whole thing works; I thought I could just create a ConfigurationContainer, include the reference to a static function in each of my models with references to their super-class’s static function of the same name (so I can add a .EnableReferences(p => p.Id) since all my models inherit from a base model with an ID property), and it seemed to go well until I realized that when you do .ConfigureType(), you get a ITypeConfiguration object out of it; you don’t get the ConfiguratioContainer back. Which, you know, that makes sense, but it wasn’t obvious at first.

And while there are examples in this README.md and on the official docs, the individual API features lack any documentation, and that contributed to my confusion.

So are there any plans on adding documentation comments in the interfaces’ methods at least? It would help a lot.

Thanks!

[Mike-E-angelo]

WHEW! What a project! That took a lot of work, but I gotta tell you, it’s worth it. I guess that’s part of the draw with documentation: it’s quite literally a second effort on the already Herculean effort involved in writing code.

In any case, all the major extension methods have been identified and organized into the main root namespace now courtesy of #274. That will clear up a lot of unnecessary using statements in code.

On top of that, all the methods have been documented. Well, all the major v2 ones, at least. There are a few v1 methods that I didn’t have much to do with, and I am not sure how much they are used, but everything is accounted for… I am guessing in the ballpark of 150 extension methods. 😱

I’ve been taking a few notes and some further work in the wiki to flesh out the documentation even more, captured in #282. However, all the documentation for the code is in there, and ready to be reviewed if you so fancy. I’m sure there’s a few typos in there, so don’t be afraid to point them out or even better, send a PR. 😁

You can check these out in our new preview feed here:

https://ci.appveyor.com/nuget/extendedxmlserializer-preview

Please be sure to select Browse and enable Include prerelease in NuGet explorer:

PS: I also wanted to say that the v3 that I mentioned earlier has been shelved. Or at least, how I originally planned it. It was far too ambitious and its vision was far too involved. However, getting back into the swing of things here with the documentation, it’s tempting to simply do a v3 XML serializer and try not to be everything to everyone (including JSON support, for instance, etc)… something to mull going forward. 🤔🤓

(Of course, now that I am heavily involved here with v2, I kinda like where this sucker is sitting on its own, as well 😆)

[Mike-E-angelo]

Haha yeah @fdrobidoux you are correct here, this is a bit of a sore point for this project. The problem is no one likes writing documentation, especially me and especially after spending so much time coding it. 😇😆🎉

I have done my best to document high level functionality. The issue we’re running into now is that v2 is going to be essentially put into support mode while we build out v3. I am sure you will not be the last person asking for this, so I will leave this up as a task on this board and I will be more than happy to coordinate with anyone who would like to do a PR.

FWIW, I did consider doing a sweep of a Ghost-Doc or something similar, but to me it’s worse to find documentation where it’s obvious that’s what the developer did. IMO, documentation is a major story and should be given the same amount of intensity as the code itself. The good news is that the code is “settled” so it will not change for v2, the bad news of course is that there is a v3 coming up (I swear! 😂) and I do not have the cycles at present to cater to this. I hope that makes sense.