Create great docs about fsharpx.collections HOT 12 CLOSED

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

from fsharpx.collections.

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.)

from fsharpx.collections.

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.

from fsharpx.collections.

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?

from fsharpx.collections.

They are built with FSharp.Formatting during release build.

from fsharpx.collections.

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?

from fsharpx.collections.

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

from fsharpx.collections.

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.

from fsharpx.collections.

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

from fsharpx.collections.

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.

from fsharpx.collections.

"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

from fsharpx.collections.

Pretty sure this issue is obsolete.

from fsharpx.collections.