Chapel: Add documentation for compiler-defined variables

[Rapiz1]

Variables(or symbols?) like boundsChecking are defined by the compiler and have certain values. Users could run into unexpected behavior when they try to use the name of the symbol.
Also, a module author had better respect these variables when trying to accomplish some internal checking.
So I think it's important to document this.
https://github.com/chapel-lang/chapel/blob/4d7fee8d0070b8336ccd52a683b26c5b34aa7520/compiler/AST/type.cpp#L881-L899

[ram-nad]

I would like to work on this. Should the new document be added under technotes?

[krishnadey30]

You can work on it @ram-nad. @ben-albrecht can tell more about where to add in docs.

[ben-albrecht]

@ram-nad - Another good question is _which_ compiler-defined variables should be documented publicly.

Should the new document be added under technotes?

Tech note seems like a reasonable starting place for location.

I would suggest following the guidance in the design docs for proposing answers to these questions.

[ram-nad]

@ben-albrecht Sir, should we open a new issue, to decide this or we can discuss in this issue itself?

[ben-albrecht]

@ram-nad - I think we can use this issue.

[ram-nad]

Sir, as per my understanding, except for chpl_overloadSetsChecks all the checks are used somewhere, in the standard library. I am not sure about use of _privatization and _local but rest, I feel can be used in user-defined libraries as well.

[ben-albrecht]

I would suggest coming up with a list of proposed variables in a comment here and then sending a mail to the mailing list with a link to it. See the suggested template from the design doc linked above.

I suspect other devs may have strong opinions about what should or should not be included. It's also worth noting that anything with a leading _ or chpl_ is considered internal because the behavior may change at any point across releases without proper deprecation. If we do document any internal variables, they should include that in their documentation.

[ram-nad]

Sure sir.

[ram-nad]

The variables that are proposed to be documented for public under Technical Notes section:

• boundsChecking
• castChecking
• chpl_checkNilDereferences
• chpl_warnUnstable
• _privatization
• _local

[e-kayrakli]

I think we're talking about documenting such variables for the end users to use in their codes, if that's the case I don't see much use in any except boundsChecking and _local (but first we need to rename it). I wouldn't object to others strongly if there is a real use case that I am not seeing. Except for _privatization:

In relatively recent past (one or two release ago) I tried to turn this off but got into some issues, so we may have some places where privatization is hardwired to be on. Maybe something that can be fixed or we just make privatization an integral part of the language and remove the flag altogether. Beyond that we want to make some generalization in privatization and make it user-facing to some extent. Bottom line for this issue is there are some issues with privatization and a long-standing desire to rework its implementation. I would try to avoid exposing as little as possible in the interface.

[ram-nad]

As I understand it, chpl_warnUnstable can be used to warn about features that are likely to be deprecated. C++ also has this feature. A feature like this will be useful for Chapel developers as well.

[bradcray]

My main reaction to this topic is that I think all of these things should be considered to be in the category of "could change or be renamed or whatever at any point in the future" for the time being (in the sense that none of them were developed with end-users in mind, as their names typically reflect, and none have really received any design effort in that direction). For that reason, documenting as a technote seems like the right way to go for now and as long as the "subject to change" caveat is clear, I'm OK with proceeding with this.

[Rapiz1]

I opened this issue because even if these variables should not be used by users, they should be documented to prevent users from declaring the variable with the same name. Or it could be confusing:

{
    var boundsChecking = false;
}
writeln(boundsChecking);
// Will compile and print 'true'

Also, I think it's fine to leave chpl_* and _* undocumented. The names of variables show they're reserved. But variables like boundsChecking need documentation for the reason above.

[bradcray]

I don't believe a user could get into trouble by declaring variables with the same name (the user's should always win). Cases like the one you show above may be confusing, but I think the user who wrote that code was pretty confused to begin with (?). That said, it would be better if we named such variables with chpl_* to better indicate that they're not intended for end-users. All that said, I'm still not opposed to documenting them, with the appropriate caveats.