Repository navigation
XML Documentation on all public methods #35
Description
The Problem
Howdy! So, I've started to play around with SqlKata on a pretty large project with a lot of team members. The existing documentation has been very helpful to get started with the basics. However, I've found myself reading the code quite a bit to get an idea of how more complex scenarios work.
The Use-Case
While this makes a case for simply beefing up the existing github website, I believe it would be more helpful to include detailed XML documentation for public members and classes. Most developers I know tend to explore a new library via:
- An IDE, by exploring XML documentation comments in the IDE's intellisense tooltip box
- Exploring a complete reference website, which can be generated from a project with XML documentation (doxygen). This could even be hosted on the Github site.
- Lastly, exploring the code - which becomes clearer with XML documentation comments.
The Question
Would this be a worthwhile contribution? Some developers leave these out as a choice, as to not clutter the code itself. If this is something that would be considered helpful, I'd gladly volunteer (without any promises as to timeframe) to begin writing this documentation. Thoughts?
IssueHunt Summary
Backers (Total: $10.00)
boostio ($10.00)
Submitted pull Requests
Become a backer now!
Or submit a pull request to get the deposits!
Tips
- Checkout the Issuehunt explorer to discover more funded issues.
- Need some help from other developers? Add your repositories on IssueHunt to raise funds.
Activity
ahmad-moussawi commentedon Dec 8, 2017
Hi @natepisarski, the short answer is absolutely yes.
But keep in mind that the package is still in beta, while the majority of the API will stay the same, I can't guarantee that the public API will not change, especially that I am planning to add many useful features to it the soonest,
So I will appreciate in advance any effort regarding the docs 👍
natepisarski commentedon Dec 8, 2017
@ahmad-moussawi That's totally okay! Updates docs after a breaking change tends to be less of an investment than writing them in the first place.
There's approaches I've seen (that are all overkill for the current state of the project) like leaving a
[Documented("12-08-2017")]and checking against a history of breaking changes automatically in the unit tests.Once I get a bit more well versed in the code I'll put up a documentation PR. I'd find it super helpful, and I bet plenty of people will as well. Thanks for being open to it 🥇
ahmad-moussawi commentedon Dec 11, 2017
That really cool, please let me know if you I can help in this also
IssueHuntBot commentedon Sep 14, 2018
@BoostIO funded this issue with $10. Visit this issue on Issuehunt
IssueHuntBot commentedon Oct 9, 2018
@anonymousjaggu has started working. Visit this issue on Issuehunt
Rajesh270712 commentedon Jun 25, 2026
Hi, I would like to work on this with a focused first pass adding XML docs for the query execution extension methods in
SqlKata.Execution/Query.Extensions.cs. I validated the branch withdotnet restore,dotnet build --no-restore, an XML doc coverage script showing62public members and0missing docs, anddotnet test --no-restore --no-build --filter 'FullyQualifiedName!~MySqlExecutionTest'(334passed,1skipped). The full local suite only failed the MySQL integration tests becauseSQLKATA_MYSQL_HOST/MySQL env is not configured locally.If this direction looks aligned, could you assign this issue to @Rajesh270712? I will avoid duplicating work if someone else is already handling it.