This is sort of an addendum to #647.

So I've been thinking more about the huge gaps in our api-docs. Right now in HEAD, there are ~19000 documentation issues (~1000 reference errors and ~18000 missing api docs). This does not include issues with boilerplate/GhostDoc type comments. When someone builds the documentation project you're greeted with a sea of yellow messages.

My thought is how about we go through the code and add placeholders where needed. We could add either
a to be documented (TBD) tag in the description or leave it blank.

TBD approach: ( /// <summary>TBD</summary> )

• Pros

  • easy to search for when adding documentation
  • doesn't mess with build in tags like TODO and BUG
  • cleans up the '[Missing
    documentation for ...]' type messages in the api webpages
  • show the end users that we're working on the documentation and that it wasn't an oversight
  • new/existing contributors can easily see where we could use help

• Cons

  • developers with Intellisense enabled will see this in the popup and might be an annoyance
  • possible visual noise to our contributors working with the code (hopefully spurring them to add in the missing docs ;))

Blank approach: ( /// <summary></summary> )

• Pros

  • easier to search for when adding documentation (not as easy as TBD but better than nothing)
  • cleans up the '[Missing
    documentation for ...]' type messages in the api webpages
  • developers with Intellisense enabled will go about as normal since empty api docs show up just like no api docs.

• Cons

  • masks the problem of missing documentation making it harder to see what's missing
  • end users may still think that missing documentation is an oversight

My thinking lies more with the TBD approach since I've done this with documenting the namespaces as seen here (http://api.getakka.net/docs/stable/html/5590F8C9.htm). But I thought I would get your opinions first before/if we proceed with the API at large.

@akkadotnet/core @akkadotnet/contributors @akkadotnet/developers

EDIT:
Outlined below are the projects that need to be completed:

• Akka.Cluster.Sharding
• Akka.Cluster.Tools
• Akka.DistributedData
• Akka.DI.Core
• Akka.Persistence.Query.Sql
• Akka.Persistence.Sql.Common
• Akka.Persistence.Sqlite
• Akka.Serialization.Hyperion
• Akka.TestKit.Xunit
• Akka.TestKit.Xunit2
• Akka
• Akka.Cluster
• Akka.Cluster.TestKit
• Akka.FSharp
• Akka.Persistence
• Akka.Persistence.FSharp
• Akka.Persistence.Query
• Akka.Persistence.TestKit
• Akka.Remote
• Akka.Remote.TestKit
• Akka.Streams
• Akka.Streams.TestKit
• Akka.TestKit