Comments and interface files

Question

When I comment, I usually use three slashes so that my comments will be included in intellisense boxes. Interface files do not seem to be compatible with this method of commenting, however. When I place a comment above a value declaration in an fsi file, that comment is included in intellisense for all clients of the module being described, but not within the module itself. When I place the comment above the value's definition in the fs file, intellisense for that value works within the module implementation only. I would like to be able to write one comment for a value which is included in intellisense popup throughout the entire project. Is this possible?

Answer 1

Hi

when you want your comments to be included in intellisence then you should give XML comment which is just giving three slash above definition of a Method or Property or class etc. like this :

    /// <summary>
    /// Give your comment here.
    /// </summary>
    public class X
    {
    }

Hope this helps.

---

One good question is equivalent to ten best answers.

Answer 2

Hello Shyam Kr! Welcome to the F# forum. I'm afraid your C#-based answer that did not even address the question was not actually helpful.

Kevin,

I'm not sure why you would want documentation comments in the fsi file to also be replicated in the fs implementation. I would consider the current behavior to be a feature, since I don't need to clutter my implementation code with documentation comments, and yet I still get intellisense in all my code that calls the implementation. Not having intellisense inside the implementation file doesn't really bother me, because the actual source code is right there in the same file, and that's more informative than a documentation comment anyway.

Answer 3

Help me understand the issue. If I create a new F# Console application and add the following to Program.fs:

/// <summary>
///  This is an xml comment for an F# interface.
/// </summary>
type IUser =
    abstract member Name: string with get

[<EntryPoint>]
let main argv =
    let josh = { new IUser with member x.Name = "Josh" }
        
    0 // return an integer exit code

Hovering of the implementation of IUser correctly displays the xml comment. Is this not happening in fsx files?

Joel,

Not having intellisense inside the implementation file doesn't really bother me, because the actual source code is right there in the same file, and that's more informative than a documentation comment anyway.

What if you deliver your code in a way that other developers won't have access to your contracts? They should be commented.

Answer 4

Joshua Belden:

I'm actually talking about fsi files, not the type of interface you are using in your example.

Answer 5

Hello Shyam Kr! Welcome to the F# forum. I'm afraid your C#-based answer that did not even address the question was not actually helpful.

Kevin,

I'm not sure why you would want documentation comments in the fsi file to also be replicated in the fs implementation. I would consider the current behavior to be a feature, since I don't need to clutter my implementation code with documentation comments, and yet I still get intellisense in all my code that calls the implementation. Not having intellisense inside the implementation file doesn't really bother me, because the actual source code is right there in the same file, and that's more informative than a documentation comment anyway.

Joe Mueller:

Let's say we are reading the implementation of function A. Function A calls out to three other functions: B, C, and D. To understand A, we must first perform the task of understanding B,C, and D. You propose that we should accomplish this task by reading the code of B,C, and D, and then returning to A. However, B,C, and D may themselves call out to other functions. I think that by taking your approach, we could fall into a rabbit hole, losing sight of what we originally sought to do: gain an understanding of A.

Whether B,C, and D are implemented in the same module as A or not seems irrelevant to me.

One point of clarification. I don't want my interface comments to be replicated in the fs file; I want them to be queryable from the fs file via intellisense. I don't think this would clutter the fs file at all.

Answer 6

Let's say we are reading the implementation of function A. Function A calls out to three other functions: B, C, and D. To understand A, we must first perform the task of understanding B,C, and D. You propose that we should accomplish this task by reading the code of B,C, and D, and then returning to A. However, B,C, and D may themselves call out to other functions. I think that by taking your approach, we could fall into a rabbit hole, losing sight of what we originally sought to do: gain an understanding of A.

Whether B,C, and D are implemented in the same module as A or not seems irrelevant to me.

One point of clarification. I don't want my interface comments to be replicated in the fs file; I want them to be queryable from the fs file via intellisense. I don't think this would clutter the fs file at all.

Kevin,

Does your documentation comment for function A also document functions B, C, and D? If not, why would you need to read the body of functions B, C, and D in order to understand function A? I can't speak for anyone else, but I try to make my F# functions have a single responsibility and a good name. Those two things plus the function signature are generally more than enough to make any documentation comments largely redundant. If I can also scroll up a bit and skim the function body, I've got all the information I could possibly need.

That said, even though what you're asking for doesn't seem like a very high priority to me, it does make sense and I can see where it would be convenient. I would suggest making a feature request on UserVoice - you'd have my vote, for what it's worth.

Personally, an F# signature-file feature I would place at a much higher priority would be the ability to generate a signature file directly in Visual Studio instead of having to call fsc.exe at the command-line. If I could right-click a *.fs file and generate a signature file from it, I might actually use signature files more often.

Answer 7

Everyone not Kevin:

The topic here is F# Signature Files. The issue is that if you put documentation comments in the signature files, you see those comments in intellisense everywhere in your solution except for the actual implementation file.