search

fsprojects / FSharp.Formatting

F# tools for generating documentation (Markdown processor and F# code formatter)
https://fsprojects.github.io/FSharp.Formatting/
Other
464 stars 156 forks source link

API reference for Property #296

Open zealisland opened 9 years ago

zealisland commented 9 years ago

It seems the API reference generated for "Property" is questionable.

For example, look at the doc here: http://fsprojects.github.io/FSharpx.Collections/reference/fsharpx-collections-experimental-timeseries-1.html, pay attention to "StartDate", which is a property with a getter and setter

image

However, the generated doc shows it as two methods

image

One cannot really tell what it is and which one is getter and which one is setter.

Moreover, the signature for the 2nd one (which corresponds to the setter) does not seem to be right, it shows as

image

Should it be DateTimeOffset -> unit?

matthid commented 9 years ago

I actually looked into this (especially the signatures) some time ago and postponed it after noticing that this seems to be non-trivial to fix. The problem is that all you see is directly given by FCS and (at the time) quite some refactoring had to be done to workaround FCS giving this signature. And actually I don't think it's a issue in FCS either we just inspect properties not "deep" enough (but it could very well be a FCS bug as well).

If someone takes a look at this: While investigating I found a related issue with constructors as well. The signature of constructors are always shown as "unit -> unit" (possible not true anymore). There are unit tests for both here: matthid@e4592c200966087f170e2fcd8cff42ed1b87d13a Those unit tests assume we want to have "unit -> Class" for constructors, only one entry for a property (instead of getter and setter) and a simplified signature (type only or "index -> Type" for indexed properties).

As I noticed some other FCS API changes which could help here I might take another look at this once I find some time, if nobody takes it in the mean time.

dungpa commented 9 years ago

@matthid I'm pretty sure this is doable by current state of FCS (at least for F#). The issue might be that FSharp.Formatting used an old metadata reader and hasn't been updated when FCS evolved.

For example, we could generate property getters and setters at the same place in VFPT: https://github.com/fsprojects/VisualFSharpPowerTools/blob/ca4d95583062519b581b108497a4448b947c9212/src/FSharpVSPowerTools.Core/SignatureGenerator.fs#L807-L810.