[Feature] Some kind of documentation comment parsing.

Is your feature request related to a problem? Please describe. This is really just a QoL or convenience feature in the category of "add features IDEs often provide".

Describe the solution you'd like Now "parsing" really is a bit hyperbolic here. What I was thinking is to simply grab blocks of commented lines directly preceding functions and symbols and displaying them together with the signature (speaking of vscode here, I don't know how much of this would be done on the language server side).

In idea this would be very similar to Pythons docstrings (for reference). Note that Pythons docstrings must be the first thing within a function. One reason for this is because in Python docstrings are available as properties at runtime. As KOS doesn't provide such a feature, it would be irrelevant (or rather, a style decision) whether these comments should be within or in front of functions.

Depending on the scale, some exception would have to be made anyway. For example, If all symbols and not just functions are to be considered, the doc comment would have to be in front of symbols like variables as they don't have an inner scope. This is why I would propose to put the comment in front of the symbol similar to how Java and I think C# handle it and putting the exception (if this is wanted at all) with file level doc comments, placing these at the top of the file.

As for where file level comments would be displayed, this is an interesting question. The vscode python extension displays module level docstrings when hovering over imports, I guess the KOS equivalent would be runpath or the include directive. I'm not sure how dificult this would be to implement and it's not really part of my suggestion. More a bonus on top of it. The important thing here really are the function doc comments.

Describe alternatives you've considered In addition to simply grabbing a block of commented lines the server could also try and use that comment to find type information, parameter hints and it may also be possible to grab info from the official decoumentation of KOS to provide this functionality for built in symbols in addition to the existing types. This would have the added bonus of making the type inference feature and thus the suggestions more reliable. Really similar to how Python did it before type hinting became part of the standard. In Python 2.7 we used to add comments describing the types of things and IDEs would grab those to provide static analysis and suggestions.

A file level comment could be used to provide info for arguments passed to the script. Essentially like parameter hints but for executing kos scripts like this `RUNPATH("some_script", arg, arg1, arg2).

Going even further, when a standard is found, the extension could provide completion within the comments and an linting rule(s) could be added to check if symbols are properly documented.

All these are more bonus features than alternatives really.

Additional context As kOS doesn't provide inherent documentation features, this would imply setting some kind of standard. In the very least that standard would be requiring comments before symbols or perhaps even with a special characer (kind of like directives). If typing and parameter hints are to be extracted, that would have to be standardised to. I'm very open to suggestions here, I don't really have a concrete idea. But I do have a pattern that I'm currently using in conjunction with a script to remove comments in order to shrink file size and a planned script to extract these comments and make a javadoc style html or markdown document out of them.

Consider this:

//@ ----------------------------------------------------------------------------
// Returns a string containing a horizontal line of the given width made of the
// given character
// -----------------------------------------------------------------------------
// @PARAMETER
//    width [string]    The desired width of the line
//    ch    [string]    The character to use for filling the line. Note: a multi
//                      char string can be passed but will result in the overall
//                      width being multiplied by it's length. The function is
//                      designed to be passed single characters and will not
//                      account for anything else.
// -----------------------------------------------------------------------------
// @EXAMPLE
//    ...
// -----------------------------------------------------------------------------
// @SEE 
//     str_fdrawLine For drawing framed lines (i.e. "|=====|")
// -----------------------------------------------------------------------------
FUNCTION str_drawLine {
...
}

Explanation:
the //@ is what signals a doc comment. It will be what I look for in my doctool to identify them. The divider lines I added are purely for show, as is the 80 char limit, the tool will ignore these. I took strong inspiration from Python and markdown here, meaning I tried to make my doc comments readable in plain text as well as machine parsable. In fact, I'm thinking about simply pumping these comments into a markdown to html converter with some custom preprocessing.

The comments are made from what I call blocks. The first block is always the description. I'm thinking about using the first paragraph as a short description. This is something the extension could do as well, instead of showing the entire comment on hover, only show the first paragraph and show the entire comment only when the "show documentation" function is used.

I added an @ to the other blocks to make them easier to differentiate from language features, this is especially useful in the example block (I guess, that one is very experimental) as it would contain (hopefully) valid kOS code including terms like PARAMETER that are also used in the commets. This could also be one thing the extension uses to provide completion in these comments (I.e. suggest @PARAMETER) and in the @SEE it could suggest symbols just as it would in regular code.

I hope the blocks are relatively self explanatory. But for completeness:

The @PARAMETERS block contains names, types and short description of the paramters. I haven't decided yet if I want to add something special for optional (or default) parameters or if I'm just going tom ention the default value in the description. The extension detext default parameters already so that's not very important here.

The @EXAMPLES block has no content because I have absolutely no idea how to implement that. I'll likely just take it as a raw block of markdown.

The @SEE is supposed to work like the similarly named block of Javadoc comments. Simply a reference to another symbol. I'm not sure if I want to try and look these up to ad links in the documentation or if I'll just add these as a plain table. Considering I don't plan to spend huge amounts of time on this, the latter is more likely.

So yeah, all of this is very experimental and in flux. It serves more as a reference and idea as to how a doc comment could look rather than a direct proposal for a standard. Type hinting is something I've been thinking about before and I was thinking whether it was worth it's own issue but I haven't come up with a good way to add type information to the code without breaking the kOS interpreter while keeping it comfortably human readable. Comments are pretty much the only way so this kind of includes this feature. The other Idea I had was adding comments similar to these parameter block on the same line as the parameter declaration. Let me know if you want me to open a seperate issue for this.

I realise that this is a bit more than fixing an inconvenience. It's a whole new feature and likely involves considerable work so I would consider it lower priority. That said I don't know how much effort it would really be. I'd also be happy to share my progress on the doc comment parser script, even though it is more meant as a quick and hacky solution for personal use. Especially the kind of standard I come up with might be of interest. As I'll use either Python, Kotlin (if it gets too complex for a simple script) or perhaps even kOS itself, the actual code is probably of less interest here.

jonnyboyC / kos-language-server

[Feature] Some kind of documentation comment parsing. #165