Add docs to System.Win32.File and System.Win32.File.Internal

[zlonast]

Description

I want to document the entire repository.
I think this pull request is a good starting point to start writing documentation.

Motivation and Context

I want to add documentation because:

1. want to know what errors the function throws.
2. want to know if it is atomic, and if not, how it is violated.
3. want to add basic documentation.
4. want to reimplement this in packages above like directory, cabal, file-io and so on.

Types of changes

• Add more docs

Checklist:

• Changes to a uniform style are possible.
• Updated the documentation accordingly.

[zlonast]

@Mistuke What do you think about such documentation?

[zlonast]

For some reason, if you try to comment on an enum, everything dies. like #{enum AccessMode
I fix it :)

[Mistuke]

@Mistuke What do you think about such documentation?

I'm not against it. We've historically not done this because win32 is supposed to be a thin wrapper around the API and we use the exact name as the c API so you can find the docs.

That said I can see the appeal of wanting to do this as it makes stuff like language servers report the documentation. However since you are copying significant portions of the text from msdn this triggers copyright issues.

The license for these docs seems to be https://github.com/MicrosoftDocs/win32/blob/docs/License, so the text is CC-BY-4.0 and any code MIT.

These are compatible licenses with BSD 3 but the terms of the license require the notices and the license be preserved somehow https://github.com/MicrosoftDocs/win32/blob/docs/LICENSE#L210 and so I'm unclear whether this means win32 must also adopt these licenses (and so become triple licensed)

Also if you've copied the text from the learn.microsoft.com this is more vague as there's no outgoing license on the site. Only a terms of service that covers everything broadly https://learn.microsoft.com/en-us/legal/termsofuse#notice-specific-to-documents-available-on-this-website

For the reasons above I'm going to be cautious here and say this isn't something I can approve on my own. And probably needs some discussion with the CLC.

Any opinions @bgamari @RyanGlScott or am I being too paranoid here?

[RyanGlScott]

What about just linking to the relevant learn.microsoft.com URLs? That should avoid copyright issues, and it would avoid needing to keep our Haddocks in sync with upstream changes.

[Mistuke]

Yeah I guess it depends on what the goal is. msdn links tend to not be overly stable. I've had the change in the past. But linking won't get you haddock which I guess was the purpose of this change. Sent from my Mobile

…

On Sun, 22 Jun 2025, 14:14 Ryan Scott, ***@***.***> wrote: *RyanGlScott* left a comment (haskell/win32#242) <#242 (comment)> What about just linking to the relevant learn.microsoft.com URLs? That should avoid copyright issues, and it would avoid needing to keep our Haddocks in sync with upstream changes. — Reply to this email directly, view it on GitHub <#242 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAI7OKLLRMX7NJSPGDUZUK33E2T35AVCNFSM6AAAAAB7V27MF2VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDSOJUGIYDSMZYGY> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[zlonast]

It's worth noting that commenting ffi is needed to make it easier for people to look at the details of how the code works under Windows. I think leaving only links we hit the usability a little, but it's still bearable.

It's worth noting that any code located in System.Win32.File is already its own explanation of how it works, apparently my desire to comment ffi calls is unnecessary due to licenses.

I think it's worth clarifying my goal. I want to make Windows errors more visible, as well as comments about atomicity within a single volume or other details that are not obvious now.

[zlonast]

To put it simply, the packages above are like directory and cabal, I just don’t know how win32 behaves and rely on the fact that this behavior is similar to unix.

[zlonast]

@Mistuke @RyanGlScott I removed the quote from the text, do you think this is enough? Or can I only leave links?

[zlonast]

I added the final description that I want to see, I think now it makes sense to look at what needs to be cut so as not to have problems with licenses 🤔