The JADE 2022 release meets tomorrow’s business demands.
In other development environments I can often hover over a method usage and see some documentation for the method - e.g. a description of what it does, what it returns, what parameter it takes and the meaning of those parameters.
E.g. JSDoc https://en.wikipedia.org/wiki/JSDoc
Hovering over a Jade method call only shows very basic facts. It would be great if this could be enhanced.
At a minimum, if there was just something like
myFancyMethod(x, y: Integer): Boolean;
@@desc: This is my method description
/*
Other method comments
*/
vars
...
this would be very beneficial.
Craig Shearer
The problem with a convention based approach is that existing systems already have their own approaches, where we've used method templates to insert headers with method descriptions, etc.
In order to avoid the need for us to go back and update potentially millions of methods to follow a new convention, it'd be more flexible if we could implement a method or external function somewhere, which given a method (or any schema entity for that matter), would return the description we'd like displayed after finding it in our method source & formatting as required.
Ah, yes I'd forgotten about the text on a method being shown. As has been pointed out, it's not particularly convenient and would be great to be able to edit it in the method itself.
I'd be happy to have a convention-based approach and show the first comment block prior to the vars/begin of the method.
What if Jade followed some simplified hierarchy of what to show in the bubble help? Text, failing that first comment block, failing that the JSDoc like format, failing that the first 5 lines of code. JSDoc like could be a second phase and use the "variable elements" as per the Method Templates.
Once the autocomplete started showing method text, I started using that more frequently for documentation on method usage. @Kevin is correct though, not being able to see/edit the method text in the browser is a barrier to using it versus opening another window. While I do just use Alt+M, T to open the new window to enter the text, having it visible in a UI element to directly edit would make it more usable and also let you more easily see the method source while editing the method text. It would be good for this to be available both in the class browser and also on the "senders browser" style forms that are displayed for things like implementors, references, browse status list, browse changed methods, etc.
The method text is shown when you hover over it as well, so if that were to contain the description and any other details, then you'd see it.
However, we're also in the habit of describing the method within the source rather than using the text field because that cannot be quickly edited alongside the method source.
We'd ideally use the method text field for documentation as that doesn't involve changing the method source when we just need to update the documentation (for some of us this would mean re-testing because we've touched the code).
Improving how we document schema entities in general is one of the examples listed for IDE extensions. The intention of that is to provide a UI for setting the schema entity text in a structured manner that can then be used to generate technical documentation in a friendly format.