I suggest you ...

SDK Documentation

The c# SDK is seriously lagging in documentation. By that I mean IntelliSense documentation: it would be awsome with some "in line" documentation for methods and properties in the SDK

59 votes
Vote
Sign in
Check!
(thinking…)
Reset
or sign in with
  • facebook
  • google
    Password icon
    Signed in as (Sign out)
    You have left! (?) (thinking…)
    jeppe shared this idea  ·   ·  Flag idea as inappropriate…  ·  Admin →

    7 comments

    Sign in
    Check!
    (thinking…)
    Reset
    or sign in with
    • facebook
    • google
      Password icon
      Signed in as (Sign out)
      Submitting...
      • AdminDemis J Bellot (Developer, ServiceStack) commented  ·   ·  Flag as inappropriate

        And we have but you haven't noticed because there are thousands of APIs, like I said we've been documenting our newer features like our newest JWT and API Key Auth Providers. OrmLite public APIs also have a lot of API docs.

        You can continue to criticize that we've done nothing, but that isn't true, e.g. we've spent considerable time and effort on documenting the newest ServiceStack Templates feature and continue put a lot of effort in our Release Notes (for many years) to describe each feature.

        You're just not going to notice until the majority of our APIs are documented, a lot of which are self-documenting and adding API docs would be redundant and add unnecessary noise. Our focus is definitely on having a readable, easy to use and self-documenting API which we prefer not to require any API docs as its much better for the source code should be readable and not rely on having its behavior hidden in API docs. It's also impossible to determine what the most commonly used APIs are as there are no metrics we can use to sort by it.

        It's not a matter of just deciding to spend the time to do it, spending time on this always takes away from something else and there's a lot more higher priority tasks we have to work on. It also has very low diminishing returns as we could stop everything and spend months on it and people would still not be satisfied unless their APIs they use most are covered.

      • Anonymous commented  ·   ·  Flag as inappropriate

        It doesn't have to be an all or nothing sort of effort. I mean, at least do something. Focus the effort on the most commonly used APIs.

      • Anonymous commented  ·   ·  Flag as inappropriate

        Sounds like an excuse to ignore the very clear demand for having better documentation. 56 + 3 of my votes should have told you this. After not having any sort of response for this suggestion for so long, I don't expect anything.

      • AdminDemis J Bellot (Developer, ServiceStack) commented  ·   ·  Flag as inappropriate

        @Anonymous You're greatly underestimating how long it would take to document the thousands of APIs in ServiceStack, this is nowhere near an overnight fix or something that can happen in a single release even if we halt all development and drop all other higher priority requirements we're currently working on.

        Our preference is to use readable API and property names so the APIs are self-documenting, our new features also include more detailed documentation as seen in the flagship feature of the last release http://templates.servicestack.net

        A release dedicated to "Documenting all existing APIs" can only happen after development has stabilized and we've implemented all higher priority features which is something we want to get done as fast as possible but we're still a long ways off.

      • Anonymous commented  ·   ·  Flag as inappropriate

        The fact that this has been here so long and not taken into consideration by Servicestack tells me this isn't a priority, even if it took a jr dev maybe 1 day to do, it doesn't matter apparently.

      • Anonymous commented  ·   ·  Flag as inappropriate

        I agree. I don't like having to go online to lookup what something means when it isn't self explanatory. It's a waste of time and should take less then a couple of days to complete. I don't think ServiceStack realizes this is a major pain for people who didn't develop the product and don't want to read the randomly scattered documentation that exists on the wiki.

      Feedback and Knowledge Base