Implement description for variables

[Kreyren]

lisp has primitive defvar which can be used to define variable, it's default value and description (which describes what is the variable used for in the code)

; Syntax
(defvar identifier value description)

; Practical: Define variable 'crab' that stores variable 'cool' by default and describes what it is used for
(defvar crab "cool" "This variable is used to do cool things with crabs")

; Stores value "wow" in variable crab instead of 'cool'
(setq crab "wow")

Proposing this to be implemented in rustlang where the idea is to make huge projects more understandable by the readers without the need to siv through the code.

---

Integration with rustdoc?

In lisp implementations such as emacs lisp (elisp) these are used in the built-in manual (opennable through C-h v system-type) stored such as:

and defined:

I think that this could be integrated nicely with rustdoc

IDE integration?

Expecting in editors such as theia to get a description about the variable on mouse hover.

[gbutler]

Doc Comments and Comments already fill this role for everything other than local variables.

Properly written code should not ever need explanations for the LOCAL variables as the names alone should be sufficient to tell the story. If the names are insufficient, that is a problem of the person writing the code not being clear. That same person will write unclear/useless comments or descriptions (especially if optional) and so there is nothing to be gained.

A responsible coder already gives meaningful and descriptive names to local variables (though sometimes a meaningful name can be 1 character in a local context and sometimes for clarity shorter is better for local variables).

For parameters, global variables, etc. that make up part of the interface, there already exists Doc Comments and tooling that supports those.

[Kreyren]

Doc comments and comments are not always an option e.g. if the variable is sourced from a library on a complicated project where it has to change value as needed -> Would require duplicate code and comments would conflict one another.

I disagree that properly written code tells the story as the identifiers are always made to be generic without any description to why they are set and what are they used for (see the example with ansi-color-context above).

[gbutler]

@Kreyren

Doc comments and comments are not always an option e.g. if the variable is sourced from a library on a complicated project where it has to change value as needed -> Would require duplicate code and comments would conflict one another.

I'm not sure what you mean by this. Could you provide a specific full example?

@Kreyren

I disagree that properly written code tells the story

It 100% does. The key word being "Properly Written". Improperly written code won't tell the story. Those who don't write code that properly tells the story won't be bothered to write comments/descriptions that tell the story any better (if they'll be bothered to write them at all).

In other words, you're seeking a technical solution to a problem that already has technical solutions that only don't work when improperly used. Adding another technical solution that can also be improperly used won't change anything for code written by the careless. The careful already have good solutions in: 1) Comments, 2) Documentation Comments, 3) (MOST IMPORTANT OF ALL) Good code structure and naming of things.

[CAD97]

@gbutler

for everything other than local variables.

Actually, you can put doc comments on local variables! (And any other statement that supports attributes.) You get a warning that rustdoc doesn't render the comments, but it's not an error, and you're perfectly allowed to add doc comments to your local variables saying what they're for.

Of course they could just be a regular comment as I don't think there's any tooling that would use that structured documentation, but you are allowed to put it there.

[Kreyren]

The idea is being able to assign a documentation to a variable definition to avoid going through the code to understand what it is supposed to do.

For (not ideal) example in the godot-rust which is library using bindings written in rustlang to be used as a scripting language for godot (the game engine).

You have variable definition such as godot-rust/object.rs at master · godot-rust/godot-rust · GitHub that can always define only their generic functionality e.g. class_name where by design you only know that this variable might store a name of some class where you have to siv through the code base to understand what it actually does, but that can get confusing when there are multiple definitions https://github.com/search?q=org%3Agodot-rust+class_name&type=code where some of them do different things and are available from a different scope (and in godot-rust development you are usually changing scopes depending on the complexity of the game so this could get confusing really quickly based on my experience).

[CAD97]

It would argue your point a lot better if you could provide an example along with the extra metadata you want to attach to it. If the variable name is just class_name because it's in a generic context where it's "the name of the class we're manipulating," what metadata are you going to attach to it to make it clearer what it's doing?

[mbrubeck]

I can think of some specific cases where doc comments on variables would be useful. Sometimes I use a comment to document some important context or conditions that don't easily fit in a variable name:

// How many cats to remove at the end of the session.
// Invariant: Must be less than or equal to `cats_added` at all times.
let mut cats_to_remove = 0;

If this were a doc comment, and my IDE or editor displayed it on hover and during auto-completion, it would make the comment easier to consult whenever the variable is referenced later in the function.

This would be almost entirely a tooling change, requiring no new language features. I see little downside to this, since it just takes existing comments and potentially makes them more useful. (On the other hand, looking at existing projects that I contribute to, comments that would benefit from this are not terribly common.)

Another use case would be doc comments on function parameters, as proposed in #57525:

pub unsafe fn from_raw_parts<'a, T>(
    /// Pointer to the first element of the slice.
    data: *const T,

    /// The number of `T` elements in the slice.
    len: usize,
) -> &'a [T]

This could be used by IDEs and editors, as well as rustdoc. It has some advantages over JavaDoc style (where the argument list is duplicated in the documentation) or current rustdoc style (where there is no way to directly document a specific parameter). Doc comments on parameters could be:

1. Easy to write (no need to replicate the list of parameters in prose),
2. Easy to read (you don't need to scan some other location if you wonder “what does this parameter mean?”),
3. Easy to maintain (harder to forget to update the docs when the list of parameters changes), and
4. Useful for tooling (for example, your IDE could show documentation for the specific parameter you are currently entering).

(Of course, like variables, not every parameter needs documentation beyond its name and type. I expect this would be used mainly for functions with fairly complex signatures, or cases where a parameter has important invariants or significance not conveyed by the name alone.)

[eminence]

@mbrubeck

Allowing documentation to live next to the parameters would make it:

I often write java, which has basic support for what you describe, via the @param tag in the doc comment. Java IDEs will indeed show this information inline when requested.

There for sure have been times when this has been useful, when I needed a small reminder about some detail about a particular parameter. But I have to say that the vast majority of the time I need to read the documentation for the whole function (not just a single parameter). Sometimes this is just due to my own personal understanding of the code. Sometimes this is due to the fact that the individual parameters are much better documented in the overall function doc compared to the info in the @param tag.

I don't think any of this contradicts or refutes any of your points. I'm just thinking aloud here a bit...

[scottmcm]

@eminence

But I have to say that the vast majority of the time I need to read the documentation for the whole function (not just a single parameter).

C#, similarly, has <param name="foo>...</param> tags, and I've never liked them. Part of the problem is that, while they show during typing, there's nowhere you can hover to get VS to show them existing code -- you can hover the function name, but that show the whole function documentation and omits the parameter documentation. And because they're isolated, you end up repeating things (min needs to be less than max and max needs to be mess than min) or needing to read the full function documentation anyway, which disappears in VS when it's showing the parameter documentation. And their existence means that coding standards invariably end up requiring them, resulting in documentation that's actually less readable than if they didn't exist:

Of late I've switched to using only <paramref name="foo"/> tags instead. That means things like "Asynchronously reads the bytes from this stream and writes them to the <paramref name="destination"/> stream", which I find less annoying for both authoring and using. So I'd be far more interested in rustdoc defining a convention for referring to parameters in the documentation comment than it gaining special support for parameter comments.

[ckaran]

@mbrubeck

Another use case would be doc comments on function parameters, as proposed in #57525 :

pub unsafe fn from_raw_parts<'a, T>(
    /// Pointer to the first element of the slice.
    data: *const T,

    /// The number of `T` elements in the slice.
    len: usize,
) -> &'a [T]

+1 to this!

Adding to the tooling comment, with this ability you could have a clippy lint that verified that you documented all the parameters (and the return value) of every function. You could also have more consistent formatting for the documentation of parameters if rustdoc new that a chunk of documentation attached to the parameter itself.

[mjbshaw]

@gbutler

Properly written code should not ever need explanations for the LOCAL variables as the names alone should be sufficient to tell the story. If the names are insufficient, that is a problem of the person writing the code not being clear. That same person will write unclear/useless comments or descriptions (especially if optional) and so there is nothing to be gained.

That's an overly absolutist point of view. Just this week I needed to do this (in C++, but my point still holds). I was working on a unit test and needed to add a test assertion in a class constructor. But ASSERT_NE expands to a return ...; statement, and returning a non-void value from a constructor is not allowed. So I wrote a little lambda to contain the assertion and prevent the macro's return statement from impacting the constructor. And I added a comment explaining the purpose of the local lambda.

I know that example was specific to C++, but I think it makes a point: sometimes programmers are put in a weird spot, and documenting a local variable is not a signal of an irresponsible coder.

As for whether doc comments or normal comments should be used: I don't have an opinion.

[gbutler]

@mjbshaw

That's an overly absolutist point of view.

I really don't think that is the case, but opinions differ for sure. Opinions can be absolute in the sense that the express a strong absolutest preference.

@mjbshaw

Just this week I needed to do this (in C++, but my point still holds). I was working on a unit test and needed to add a test assertion in a class constructor. But ASSERT_NE expands to a return ...; statement, and returning a non- void value from a constructor is not allowed. So I wrote a little lambda to contain the assertion and prevent the macro's return statement from impacting the constructor. And I added a comment explaining the purpose of the local lambda.

That's really not relevant to this I would think. You are not documenting a variable that can be used by a client. You are documenting a test case and elaborating on what the test is doing. There is absolutely no need to expose that documentation outside the code. Also, I would be willing to bet that the extra documentation wasn't needed even though you believed it was.

@mjbshaw

I know that example was specific to C++, but I think it makes a point: sometimes programmers are put in a weird spot, and documenting a local variable is not a signal of an irresponsible coder.

Documenting and needing to document are two different things. If you document something that didn't really need it, that is not irresponsible, just unnecessary. If you document (or not) something that needs documentation (locally) that needs said documentation (to be reasonably understood by a programmer familiar with the language) then that is irresponsible (in most cases - I recognize that there may be exceptions). Even the exceptions are irrelevant to this proposal because the OP is mixing up the idea of documenting variables that need to be used by the client of the API with implementation details. The former belongs in doc-comments (as is already done today) whereas the latter, at best, belongs as comments in the code, which should ideally not be necessary in well-written implementation code.