codefori / codefori/vscode-rpgle

Intelligently Auto-Add Variable Name to @param Text

Open
#584 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
57
Forks
35
Avg merge
2d 3h
Merged PRs (30d)
1

Description

**Is your feature request related to a problem? Please describe.**
Currently, the hover text for a procedure will automatically add the variable name to the `@param` text. This causes the variable name to be printed twice if one is following the standard ILEDoc syntax:

```RPGLE
///
// My Subprocedure
// @param var1 The first parameter variable
// @param var2 The second parameter variable
///
```

The hover text for the above will render as:

```
mySubprocedure(
var1: ind const options(*NOPASS),
var2: ind const options(*NOPASS)
): void

My Subprocedure

@param var1 var1 The first parameter variable

@param var2 var2 The second parameter variable
```

Notice that the variable names are doubled "var1 var1" and "var2 var2".

This has lead me to start omitting the variable name in the `@param` doc. This is absolutely the wrong approach. Any changes to the parameter list that are not synced to the `@param` doc become very difficult to track down and correct.

**Describe the solution you'd like**
A change to the ILEDoc parser to only prepend the variable name if it is not found (case-insensitive) as the first word of the `@param` description. This will do the following:

* Encourage proper use of the ILEDoc `@param` tag in the syntax of "`@param` var Description".
* Add visibility of drift between the `@param` doc and the procedure definition
* By conditionally prepending only if not found, will maintain backward compatibility

As stated, the change is to the ILEDoc tag parser for the `@param` tag. It should do a case-insensitive test of the first word of the `@param` description. If it matches the variable name the parser thinks it should be, then do not prepend. If it does not match, continue with the current logic to pre-pend the variable name.

This conditional pre-pending allow the hover text to be rendered as it currently does for either syntax of the `@param` ("`@param` var Description" and "`@param` Description").

> NOTE:
> There is one case that will cause the hover text to be rendered differently. If the `@param` tag does *not* include the variable name, but the first word of the description happens to match the variable name, the hover text will no longer pre-pend the variable name. For example, assume a procedure has a parameter named `quick` and that it is documented as `// @param Quick access flag`. Currently this would be rendered as "`@param quick Quick access flag`". The conditional pre-pend logic above would find a match between the variable name `quick` and the `@param` description's first word `Quick`. As such, it would render the hover text as "`@param Quick access flag`".

**Describe alternatives you've considered**
As mentioned, the alternative is to adopt a `@param` usage that omits the variable name. This makes the reading of the source difficult and makes reconciling any drift difficult.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by locating the ILEDoc @param tag parser and the procedure hover-text path described in the issue. Verify that the first description word is compared case-insensitively with the inferred parameter name, preserving both documented forms and covering the noted matching-word edge case.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript, vscode
Domain
devtools
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
70/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.