Improve missing or boilerplate xmldoc

[sean-gilliam]

A lot of the xmldoc is great, succinct and very informative. However there is still giant swathes of missing or bolierplate xmldoc that could be greatly improved. Most of the bolierplate comments look to be auto-generated from a tool like GhostDoc.

Not to pick on one class in particular, but if you take a look at for example src/core/Akka/Configuration/ConfigurationFactory.cs you'll notice some hilariously bad xmldoc.

/// <summary>
///     Gets the empty.
/// </summary>
/// <value>The empty.</value>
public static Config Empty
{
    get { return ParseString(""); }
}

/// <summary>
///     Defaults this instance.
/// </summary>
/// <returns>Config.</returns>
public static Config Default()
{
    return FromResource("Akka.Configuration.Pigeon.conf");
}

/// <summary>
///     Froms the resource.
/// </summary>
/// <param name="resourceName">Name of the resource.</param>
/// <returns>Config.</returns>
internal static Config FromResource(string resourceName)
{
    Assembly assembly = Assembly.GetExecutingAssembly();

    return FromResource(resourceName, assembly);
}

I know there are more pressing issues at hand, but it would be nice to have clean API docs :)

[SeanKilleen]

Wondering out loud: would this make sense to submit as a number of separate issues where found, maybe with some sort of "documentation" label, so that folks can dive in to the trouble spots and address them rather than looking through the whole codebase?

I like the idea of cleaning up the xmldocs and might have some time to take that on myself (where I'm knowledgeable enough) but don't necessarily have the bandwidth / authority to scan the whole repo looking for these.

[sean-gilliam]

@SeanKilleen I'm down for multiple issues if that makes sense. Just trying to raise the awareness of the state of the xmldocs.

[Aaronontheweb]

I think this is a good idea - I try to go through and clean up these comments when I'm working on the code itself, but having a concerted issue to do this is a good first step.

Please feel free to start sending PRs for this.

[Aaronontheweb]

So this is still a major issue - all of the content on

• Unstable http://api.getakka.net/docs/unstable/index.html
• Stable http://api.getakka.net/docs/stable/index.html

Gets built from these comments. It'd be great for our project if we could raise the quality of these comments to all be at the same level as http://api.getakka.net/docs/unstable/html/F0DC1571.htm or http://api.getakka.net/docs/unstable/html/F0EE599D.htm

We could really use some help from every contributor we can get here.

[SeanKilleen]

@Aaronontheweb I'm down to help, I'm just not as familiar with the codebase itself yet (why I stuck mostly to things like renaming, build process, etc.)

I'll try to think through ways to highlight these individual areas so that others can begin to dig through them.

Are we averse to TODO items? Thinking if I can find a way to search through and slap a TODO onto a lot of these we'll at least have some focused areas for improvement..

[Aaronontheweb]

@SeanKilleen IMHO, the best tools for sorting out what docs need to be added where:

1. The compiler warnings thrown by SandCastle on API doc generation. They call out the areas where documentation doesn't exist period - not even GhostDoc. You can see an example from the BuildServer here
2. The UNSTABLE API docs here: http://api.getakka.net/docs/unstable/index.html - they call out with red warnings where missing documentation is. Tracking down the crappy documentation that needs to be improved is harder.

The way I'm working on this is incremental - start by improving the comments in areas where the code is familiar to you and follow some of the good examples @HCanber sets in Akka.TestKit in particular. He does a thorough job.

Maybe we should add a set of guidelines for how to write these?

[SeanKilleen]

@Aaronontheweb I think guidelines or a link to 1-2 specific examples would be really instructive for others and would help avoid moving from no documentation --> subpar documentation (which as you mentioned would be more difficult to find & correct).

Personally, I imagine I'll be able to dig into much more of the code after tomorrow's workshop. :)

[wilsonch0]

@Aaronontheweb @sean-gilliam @skotzko I sent Andrew email a few days ago about my possibly helping with documentation.

Aaron said above to identify targets one could first look at: "The compiler warnings thrown by SandCastle on API doc generation. They call out the areas where documentation doesn't exist period - not even GhostDoc."

Here is what I think I did: I built the SandCastle docs, extracted the "ShowMissingComponent" warning messages, from them extracted the 2nd and 3rd layers of the identifiers (for example, Akka.Actor.ActorCell.Post(Akka.Actor.IActorRef,System.Object) would yield Actor and ActorCell as values) into a tab-delimited file, loaded the tab-delimited file into Google Sheets, and did a pivot table. My goal was to be able to identify places where there were lots of missing entries. Notice that this method yields multiple hits per item -- if a summary is missing and a parameter is missing and a return is missing that's three hits.

I think I have put two files into this comment: The raw log file and a PDF that shows the top-level counts. I can make the worksheet available (it's in my Google drive or I can email it) but this box doesn't accept that file type.

According to my results (which must be second-guessed and checked for reasonability) there were about 11,000 warning messages in all. The three winners are: Cluster, Actor, and Persistence. Within Cluster, 2400 of the 2800 warning messages come from "Proto". Within Actor, 250 of the 1650 warning messages come from "Internal." Within Persistence, 210 of the 1200 warning messages come from "Journal".

I think I know enough about the mechanics to be able to fill in some of the lacunae. I know that I don't know enough to write excellent comments. But someone can point me to a particular part of the hierarchy and I can try making a few changes to the XML documentation comments, for review by more knowledgeable folks.

Clark

outputOrig.tab - Pivot Table 1.pdf LastBuild-201511111846.txt

[sean-gilliam]

@wilsonch0 I'm glad someone else is looking at this other than me :) Just a few notes:

• The classes within the "Proto" namespace come from the Google Protocol Buffer stuff, Since these classes are autogenerated, I don't think we really need to document them.
• Running Sandcastle and parsing the output is a good start, but there are cases we're it falls short, i.e. /// <param name="member"></param>. Sandcastle won't bark at this IIRC.

Besides the missing comments, the areas I see needing improving are expanding how to use the classes with some sample code in the comments and some light proofreading/editing to put some polish on the comments.

I've been slowly chipping away at this, but could definitely use your (and anyone else's) help. cc @akkadotnet/developers

[wmeints]

Is there any specific area I can help with?

[gouthampai]

I see this issue about xml doc is still open. I want to get started with helping out in the open-source community and I think this might be a good place to start. Is there some place I should start fixing the xml docs in?

[Danthar]

Well, the linked issue above is a good start. Anything on the public API that does not has decent XML docs.

[gouthampai]

Thanks @Danthar . I'll start digging in.