1. Being a feature of many mature programming languages, this is an old idea that has been discussed before. For instance, https://www.autohotkey.com/boards/viewtopic.php?f=13&t=28150
My preferred method of dealing with this is to use convention and documentation. If you want to prevent users of your library from calling the method, make it awkward to call, tell them not to call it (or just what is acceptable to call), and let them deal with the consequences of ignoring your recommendations. If calling your private method is the only way to achieve what they want, let them do it. It's not like you can stop them from making a private method public.
ECMAScript 6 uses the prefix # for private fields. One possible implementation is to replace all such symbols at load time with unique values that only the compiler/interpreter knows. For example, inside class A, #x
could internally be the string #A.x/89234
, while in class B it could be #B.x/03248
, and outside of a class it would be an error. The class name prefix allows it to be identified by a debugger (or enumerator if the field can be enumerated), while the random suffix prevents the user from using something like that["#A.x"]
As for making private methods awkward to call, one strategy is to use a hotstring to generate a prefix that can't be typed easily. For instance, in Object.ahk I used the prefix ← for private fields and a hotstring like :*:<-::←
to type it (although this was actually just to avoid key conflicts).
2. In Visual Studio, when I hover over a variable, function or type name, I get a tooltip showing the content of an adjacent comment, which is usually documentation. I find this to be fairly effective. Sometimes the comments aren't documenting what I'm hovering over, but that's because they weren't written with this specific feature in mind. Perhaps the only benefit of using a standalone multi-line string in place of a comment is that the string is otherwise completely useless, whereas the comment might relate to something else. However, I think it carries the wrong meaning.
In any case, tools already exist to generate documentation from comments. Comments are fundamentally documentation; there is no need for another type of comment.