fsprojects / FSharp.Formatting

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

Unit returning functions yield warning #936

Open johannesvp opened 1 month ago

johannesvp commented 1 month ago

For functions to be documented that return unit, a warning is returned: a parameter is missing a name. Using fsdocs 19.1.1

The code:

    /// <summary>
    /// Resets all channels ...
    /// Next to this it also disables ...
    /// </summary>
    /// <exception cref="ErrorHandeling.DriverException">An exception that is thrown when the driver encounters
    /// an exception/error</exception>
    let Disable () =
        disable read write

fsdocs output:

> 
> 2>API docs:
> 2>  generating model for 2 assemblies in API docs...
> 2>  loading 2 assemblies...
> 2>isNetCoreApp = true
> 2>  registering entities for assembly Apollo.Driver...
> 2>  registering entities for assembly Apollo.SwitchPanel.Gui...
> 2>  reading XML doc for C:\Users\Johannes.vanPutten\Documents\Salland\Products\Apollo\src\Apollo\Apollo.Driver\bin\x64\Release\net6\Apollo.Driver.dll...
> 2>  reading assembly data for C:\Users\Johannes.vanPutten\Documents\Salland\Products\Apollo\src\Apollo\Apollo.Driver\bin\x64\Release\net6\Apollo.Driver.dll...
> 2>C:\Users\Johannes.vanPutten\Documents\Salland\Products\Apollo\src\Apollo\Apollo.Driver\Dps.fs(126,8): warning : a parameter was missing a name

Same warning is produced for any public function with XML comments that returns unit.

nojaf commented 1 month ago

Can you reproduce this with the latest main?

johannesvp commented 1 month ago

Same result with v20.0.1

nojaf commented 1 month ago

I appreciate your response, but my question was specific to the latest update. The main branch received an update to the F# compiler yesterday, and I'm curious if the issue persists with this new version.

johannesvp commented 1 month ago

Not yet available at nuget, after a local build it appeared that the result is the same for 21.0.0-beta-003.

nojaf commented 1 month ago

I noticed this warning comes from this line.

I'd be happy to accept a PR to check whether the parameter type is unit or not. Would you be interested in submitting a PR for this?