Create great docs

[forki]

Docs can be found at http://forki.github.io/FSharpx.Collections/

needed for #1

[forki]

/cc @jackfoxy please review http://forki.github.io/FSharpx.Collections/apidocs/index.html

[jackfoxy]

I will review. Give me some time I have a very busy day today. For the "final" merged library I want to suggest renaming "Heap" to "OrderedQueue" and keep aliases for Heap and PriorityQueue. I also have in mind a minor adjustment to the empty binding. I think too many potential users are not familiar with Heap or PriorityQueue, and this is a more descriptive name. (This is a pairing heap implementation, btw, for those who don't know.)

[jackfoxy]

It took me a long time, but I have some minor doc changes that I will submit with the next substantive push for this project.

[jackfoxy]

I want to improve something in the xml doc for the Heap collection, and found the project does not build to an xml doc file. Looking in build.fsx I also saw nothing that looks xml doc related.@forki how are the xml docs getting built?

[forki]

They are built with FSharp.Formatting during release build.

[jackfoxy]

The Heap.empty function needs additional pop-up intellisense docs because it has a parameter, but this seems to have no affect:

///<summary>O(1). Returns a empty heap.</summary>
///<param name="isDescending">true: heap will sort descending.</param>
[<GeneralizableValue>]
val empty<'T when 'T : comparison> : bool -> Heap<'T>

Correctly builds the xmldoc

<member name="M:FSharpx.Collections.HeapModule.empty``1(System.Boolean)">
<summary>O(1). Returns a empty heap.</summary>
<param name="isDescending">true: heap will order descending.</param>
</member>

but the pop-up intellisense (testing in HeapTests.fs) only shows the summary. Is this because the project target framework is .NET 3.5? Is there any reason not to advance this project to 4.5, or at least 4.0?

[forki]

This stuff is used in 3.5 projects. Please keep it compatible

[jackfoxy]

Is there something I should do to get param intellisense to work in VS?

Empty and ofSeq are the only way to construct this collection, and the parameter is not intuitive.

The alternative I have thoughtof is to drop the parameter, make empty and ofSeq instantiate ascending order and add 2 new module functions, emptyDescending and ofSeqDescending. Of course that would be a breaking change and also undesireable.

[forki]

strange. Maybe we should use markdown XML comments like in FAKE.

[jackfoxy]

I temporarily turned on XML generation in the FSharpx.Collections project in order to observe the results in the FSharpx.Collections.Tests project. I think this methodology is sound for this test.

I have no experience with Markdown XML comments. Another alternative is to put the parameter information inside the summary part of the xml doc. This at least gets the message to the user.

[forki]

"parameter information inside the summary part of the xml"

That's basically what we do in MD style. We just omit the xml tags and everything goes into summary.

https://github.com/fsharp/FAKE/blob/develop/src/app/FakeLib/UnitTest/XUnitHelper.fs#L105 gets rendered to http://fsharp.github.io/FAKE/apidocs/fake-xunithelper.html

[jackfoxy]

Pretty sure this issue is obsolete.