@start-group/@end-group directives ignored (2.2.1)

[jclark-dot-org]

@start-group/@end-group directives ignored (2.2.1)

[jclark-dot-org]

I fixed the @return lines that had no description. For the backtick issue, I just removed the @ inside the backticks:

`@TestVisible` became `TestVisible`

And with that, it ran to completion. Only one issue, 2.2.2 doesn't appear to honor the @group directive in my class headers. For example:

/**********************************************************
 class          ApexUtil
 testClass      ApexUtil_Test
@group          core-utils
@description    Core apex utilities for use in all projects
@author         Jason Clark
@date           11/10/20
***********************************************************/

This ended up in docs/Misc instead of docs/core-utils. This wasn't an issue for me with the 1.1 version. Minor issue tho - I've got doc files now. Thanks again for the help!

[cesarParra]

@jclark-dot-org 🤔 Weird. I just ran it for the code you provided and it seems to be grouping correctly: https://github.com/cesarParra/apexdocs-docsify-example/blob/master/docs/Misc/CodeControl.md

From your comment I see it is grouping everything under Properties while in v2 non-property variables (variables without getters and setters) should be grouped under Fields so I'm wondering if v1 is still being used somehow

[jclark-dot-org]

@cesarParra I did have v1 installed at one time, let me make sure there isn't a copy somewhere

[jclark-dot-org]

@cesarParra Good call, I seem to have both:

> $ apexdocs-generate --version
2.2.1
                                                                                                                                                                                                        
> $ npm exec -- apexdocs-generate --version                                                            
1.13.8

And of course I was running with npm exec. However, running 2.2.1 crashes.

> $ apexdocs-generate -s force-app/ -g docsify -p global public namespaceaccessible private                                                       
5/13/2022, 10:57:38 AM: Parsing error Exception: Error parsing Apex Body. Line 338:4 - extraneous input '/**\n     * @description override the return value of `ApexUtil.now()` in a unit test\n     * @
param nowOverride the override value to return\n     */' expecting {'abstract', 'after', 'before', 'class', 'enum', 'final', 'get', 'global', 'inherited', 'instanceof', 'interface', 'override', 'priva
te', 'protected', 'public', 'set', 'sharing', 'static', 'switch', 'testmethod', 'transient', 'trigger', 'virtual', 'void', 'webservice', 'when', 'with', 'without', 'list', 'map', 'select', 'count', 'f
rom', 'as', 'using', 'scope', 'where', 'order', 'by', 'limit', 'and', 'or', 'not', 'avg', 'count_distinct', 'min', 'max', 'sum', 'typeof', 'end', 'then', 'like', 'in', 'includes', 'excludes', 'asc', '
desc', 'nulls', 'first', 'last', 'group', 'all', 'rows', 'view', 'having', 'rollup', 'tolabel', 'offset', 'data', 'category', 'at', 'above', 'below', 'above_or_below', 'security_enforced', 'reference'
, 'cube', 'format', 'tracking', 'viewstat', 'custom', 'standard', 'calendar_month', 'calendar_quarter', 'calendar_year', 'day_in_month', 'day_in_week', 'day_in_year', 'day_only', 'fiscal_month', 'fisc
al_quarter', 'fiscal_year', 'hour_in_day', 'week_in_month', 'week_in_year', 'converttimezone', 'yesterday', 'today', 'tomorrow', 'last_week', 'this_week', 'next_week', 'last_month', 'this_month', 'nex
t_month', 'last_90_days', 'next_90_days', 'last_n_days', 'next_n_days', 'next_n_weeks', 'last_n_weeks', 'next_n_months', 'last_n_months', 'this_quarter', 'last_quarted', 'next_quarter', 'next_n_quarte
rs', 'last_n_quarters', 'this_year', 'last_year', 'next_year', 'next_n_years', 'last_n_years', 'this_fiscal_quarter', 'last_fiscal_quarter', 'next_fiscal_quarter', 'next_n_fiscal_quarters', 'last_n_fi
scal_quarters', 'this_fiscal_year', 'last_fiscal_year', 'next_fiscal_year', 'next_n_fiscal_years', 'last_n_fiscal_years', IntegralCurrencyLiteral, 'find', 'email', 'name', 'phone', 'sidebar', 'fields'
, 'metadata', 'pricebookid', 'network', 'snippet', 'target_length', 'division', 'returning', 'listview', '@', Identifier}                                                                               
/Users/jclark/.nvm/versions/node/v17.2.0/lib/node_modules/@cparra/apexdocs/node_modules/@cparra/apex-reflection/out.js:5406                                                                             
throw A.h(q)}},               
^                                                                                                   
                                                                                                                                                                                                        
Converting object to an encodable object failed: Instance of 'minified:is'                 
    at Object.h (/Users/jclark/.nvm/versions/node/v17.2.0/lib/node_modules/@cparra/apexdocs/node_modules/@cparra/apex-reflection/out.js:514:3)                                                          
    at la.c2 (/Users/jclark/.nvm/versions/node/v17.2.0/lib/node_modules/@cparra/apexdocs/node_modules/@cparra/apex-reflection/out.js:5406:9)                                                            
    at Object.q3 (/Users/jclark/.nvm/versions/node/v17.2.0/lib/node_modules/@cparra/apexdocs/node_modules/@cparra/apex-reflection/out.js:1744:3)                                                        
    at kB.hI (/Users/jclark/.nvm/versions/node/v17.2.0/lib/node_modules/@cparra/apexdocs/node_modules/@cparra/apex-reflection/out.js:5338:5)                                                            
    at lE.$1 (/Users/jclark/.nvm/versions/node/v17.2.0/lib/node_modules/@cparra/apexdocs/node_modules/@cparra/apex-reflection/out.js:16033:19)                                                          
    at Object.pv (/Users/jclark/.nvm/versions/node/v17.2.0/lib/node_modules/@cparra/apexdocs/node_modules/@cparra/apex-reflection/out.js:469:69)                                                        
    at qn (/Users/jclark/.nvm/versions/node/v17.2.0/lib/node_modules/@cparra/apexdocs/node_modules/@cparra/apex-reflection/out.js:4005:10)                                                              
    at Object.reflect (/Users/jclark/.nvm/versions/node/v17.2.0/lib/node_modules/@cparra/apexdocs/node_modules/@cparra/apex-reflection/out.js:3999:42)                                                  
    at Object.reflect (/Users/jclark/.nvm/versions/node/v17.2.0/lib/node_modules/@cparra/apexdocs/node_modules/@cparra/apex-reflection/index.js:6:27)                                                   
    at Apexdocs._reflectionWithLogger (/Users/jclark/.nvm/versions/node/v17.2.0/lib/node_modules/@cparra/apexdocs/lib/application/Apexdocs.js:38:38) {                                                  
  dartException: dp {                                                                                                                                                                                   
<<VERY LONG JSON SERIALIZATION OMITTED>>

I was able to find the line of my code that caused that:

    @TestVisible
    /**
     * @description override the return value of `ApexUtil.now()` in a unit test
     * @param nowOverride the override value to return
     */
    private static void setNowOverride(Datetime nowOverride) {
        now_override = nowOverride;
    }

I took a guess that it didn't like the apexdoc comment in between @TestVisible and private static void... so I moved @TestVisible just below the comment. That fixed that issue, but now I've got another failure and there's no context info I can find to show where in my code it's breaking.

> $ apexdocs-generate -s force-app/ -g docsify -p global public namespaceaccessible private                                                                                                             
/Users/jclark/.nvm/versions/node/v17.2.0/lib/node_modules/@cparra/apexdocs/node_modules/@cparra/apex-reflection/out.js:5406                                                                             
throw A.h(q)}},                                                                                                                                                                                         
^                                                                                                                                                                                                       
                                                                                                                                                                                                        
Converting object to an encodable object failed: Instance of 'minified:is'                                                                                                                              
    at Object.h (/Users/jclark/.nvm/versions/node/v17.2.0/lib/node_modules/@cparra/apexdocs/node_modules/@cparra/apex-reflection/out.js:514:3)                                                          
    at la.c2 (/Users/jclark/.nvm/versions/node/v17.2.0/lib/node_modules/@cparra/apexdocs/node_modules/@cparra/apex-reflection/out.js:5406:9)                                                            
    at Object.q3 (/Users/jclark/.nvm/versions/node/v17.2.0/lib/node_modules/@cparra/apexdocs/node_modules/@cparra/apex-reflection/out.js:1744:3)                                                        
    at kB.hI (/Users/jclark/.nvm/versions/node/v17.2.0/lib/node_modules/@cparra/apexdocs/node_modules/@cparra/apex-reflection/out.js:5338:5)                                                            
    at lE.$1 (/Users/jclark/.nvm/versions/node/v17.2.0/lib/node_modules/@cparra/apexdocs/node_modules/@cparra/apex-reflection/out.js:16033:19)                                                          
    at Object.pv (/Users/jclark/.nvm/versions/node/v17.2.0/lib/node_modules/@cparra/apexdocs/node_modules/@cparra/apex-reflection/out.js:469:69)                                                        
    at qn (/Users/jclark/.nvm/versions/node/v17.2.0/lib/node_modules/@cparra/apexdocs/node_modules/@cparra/apex-reflection/out.js:4005:10)                                                              
    at Object.reflect (/Users/jclark/.nvm/versions/node/v17.2.0/lib/node_modules/@cparra/apexdocs/node_modules/@cparra/apex-reflection/out.js:3999:42)                                                  
    at Object.reflect (/Users/jclark/.nvm/versions/node/v17.2.0/lib/node_modules/@cparra/apexdocs/node_modules/@cparra/apex-reflection/index.js:6:27)                                                   
    at Apexdocs._reflectionWithLogger (/Users/jclark/.nvm/versions/node/v17.2.0/lib/node_modules/@cparra/apexdocs/lib/application/Apexdocs.js:38:38) {                                                  
  dartException: dp {                                                                                                                                                                                   
    a: is {                                                                                                                                                                                             
<<VERY LONG JSON SERIALIZATION OMITTED>>

It's probably too long to include, but ends with

      b: l7 {
        a: "Error parsing Apex doc. Line 6:14 - mismatched input '\\n     */' expecting SPACE"
      },
      '$thrownJsError': Converting object to an encodable object failed: Instance of 'minified:dB'
          at Object.h (/Users/jclark/.nvm/versions/node/v17.2.0/lib/node_modules/@cparra/apexdocs/node_modules/@cparra/apex-reflection/out.js:514:3)
          at la.c2 (/Users/jclark/.nvm/versions/node/v17.2.0/lib/node_modules/@cparra/apexdocs/node_modules/@cparra/apex-reflection/out.js:5406:9)
          at la.jh (/Users/jclark/.nvm/versions/node/v17.2.0/lib/node_modules/@cparra/apexdocs/node_modules/@cparra/apex-reflection/out.js:5433:6)
          at la.eJ (/Users/jclark/.nvm/versions/node/v17.2.0/lib/node_modules/@cparra/apexdocs/node_modules/@cparra/apex-reflection/out.js:5418:3)
          at la.c2 (/Users/jclark/.nvm/versions/node/v17.2.0/lib/node_modules/@cparra/apexdocs/node_modules/@cparra/apex-reflection/out.js:5398:6)
          at la.ji (/Users/jclark/.nvm/versions/node/v17.2.0/lib/node_modules/@cparra/apexdocs/node_modules/@cparra/apex-reflection/out.js:5449:3)
          at la.eJ (/Users/jclark/.nvm/versions/node/v17.2.0/lib/node_modules/@cparra/apexdocs/node_modules/@cparra/apex-reflection/out.js:5423:5)
          at la.c2 (/Users/jclark/.nvm/versions/node/v17.2.0/lib/node_modules/@cparra/apexdocs/node_modules/@cparra/apex-reflection/out.js:5398:6)
          at la.ji (/Users/jclark/.nvm/versions/node/v17.2.0/lib/node_modules/@cparra/apexdocs/node_modules/@cparra/apex-reflection/out.js:5449:3)
          at la.eJ (/Users/jclark/.nvm/versions/node/v17.2.0/lib/node_modules/@cparra/apexdocs/node_modules/@cparra/apex-reflection/out.js:5423:5) {
        dartException: [Circular *1]

And I can't find a class file with a Line 6 that seems to match the message. I'd prefer not to post my whole code base; is there some way to better find the source of the parsing error. I should mention that the apex is all valid, and builds an unlocked package without issue in a scratch org.

[cesarParra]

Thanks for all of those details @jclark-dot-org . Its definitely an issue with the parser somewhere, I'll investigate

[cesarParra]

I haven't been able to decipher exactly what the problem might be, but I just released a new version (2.2.2) that should hopefully better surface the error and from which file it is coming from.

@jclark-dot-org If possible whenever you get a chance can you retry with these latest version and let me know where is the issue coming from?

[jclark-dot-org]

@cesarParra Ok, that made a big difference. Here's all the output:

ApexUtil - Doc comment parsing error. Level: Method
Comment:
 /**
     * @description returns the name of the calling method, or an ancestor further up the call stack
     * @param skipMethods (optional) the number of methods in the call stack to skip.
     *        Default is 1, which returns the method that called the method calling getSource()
     *
     * @return
     */
Exception: Error parsing Apex doc. Line 6:14 - mismatched input '\n     */' expecting SPACE
=================================
CodeControl - Doc comment parsing error. Level: Method
Comment:
 /**
     * @description a `@TestVisible` private method to override any custom metadata in the org with test values
     * @param controlRecords a list of `Code_Control__mdt` records to load
     */
Exception: Error parsing Apex doc. Line 2:35 - extraneous input '`' expecting SPACE
=================================
CodeControl - Doc comment parsing error. Level: Method
Comment:
 /**
     * @description Determines if a trigger is enabled (by TriggerHandler name or SObject name) in the Code Control custom metadata type.
     *              Honors the wildcard source (`CodeControl_Default`) and system-wide source (`CodeControl_Override`)
     *              if present in Code Control.
     *              Primarily intended for use by <<TriggerService>>.
     * @param triggerHandlerName The name of the TriggerHanlder
     * @param sObjectName The name of the SObject
     * @param runDuringTests Specify if trigger should run during test execution (subject to normal Code Control settings).
     *
     * @return true if the trigger should execute

     *
     * @return
     */
Exception: Error parsing Apex doc. Line 13:14 - mismatched input '\n     */' expecting SPACE
=================================
5/13/2022, 3:54:20 PM: SchemaUtil processed.
5/13/2022, 3:54:20 PM: README processed.
5/13/2022, 3:54:20 PM: TriggerHelper processed.
5/13/2022, 3:54:20 PM: ApexUtil processed.
5/13/2022, 3:54:20 PM: TriggerHelperBase processed.
5/13/2022, 3:54:20 PM: LogUtil processed.
5/13/2022, 3:54:20 PM: DSoql processed.
5/13/2022, 3:54:20 PM: TriggerService processed.
5/13/2022, 3:54:20 PM: CodeControl processed.

Looks like it doesn't like my use of backticks, and it gets upset if I include @return without a type. I can certainly fix the second issue, but I'd like to keep the backticks for the MD output.

Thanks for all of the help.

[cesarParra]

Thanks @jclark-dot-org . I see what was the issue, I was being overly specific with how the doc should start so it was skipping comments that start with more than 2 asterisks. That should hopefully now be resolved with the latest version (2.2.3).

Now, a caveat is that it might still have trouble parsing docs as the ApexUtil example above. The reason is because it supports both the Javadoc style description style (where the description is the first sentence of the doc without using the @description tag) or using a @description tag explicitly, but not both. But in your example it might interpret that first block as the description, and then misbehave when it finds the description tag below as well.

In v2 I added the ability for custom tag support, so in this case that might be something you could use if you are interested. So for example the class and testClass portion could be turned into custom @class and @test-class tags, and that could even be paired with {@link ClassName} to get file linking support as well. For example

/**********************************************************
Core apex utilities for use in all projects
@group           core-utils
@test-class      {@link ApexUtil_Test}
***********************************************************/
public class SomeClass{}

[jclark-dot-org]

That makes sense, and I originally used @class and @testClass; I think I removed them because the 1.x branch of apexdocs didn't like them. Restoring them works much better.

One more observation on @start-group/@end-group:

This works fine:

    // @start-group Special Metadata Names
    public static final String WILDCARD_SOURCE = 'CodeControl_Default';
    public static final String SYSTEM_WIDE_SOURCE = 'CodeControl_Override';
    // @end-group

And produces:

### Special Metadata Names

* `SYSTEM_WIDE_SOURCE` → `String` 
* `WILDCARD_SOURCE` → `String` 
---

BUT, changing // @start-group ... to /** start-group ... */ does not:

    /** @start-group Special Metadata Names */
    public static final String WILDCARD_SOURCE = 'CodeControl_Default';
    public static final String SYSTEM_WIDE_SOURCE = 'CodeControl_Override';
    /** @end-group */

That produces:

### Other

* `SYSTEM_WIDE_SOURCE` → `String` 
* `WILDCARD_SOURCE` → `String` 
---

Which is probably okay, but since all other directives work with the Javadoc prefix (/**) it is a bit of an exception.

Also, I couldn't get @description to work with either the constants or the group. For example:

    // @start-group Special Metadata Names
    /** @description Wildcard and Override Settings are only used for Logging and Trigger control.*/
    public static final String WILDCARD_SOURCE = 'CodeControl_Default';
    public static final String SYSTEM_WIDE_SOURCE = 'CodeControl_Override';
    // @end-group

I suppose you could read that @description as either describing the group (which I'd prefer) or WILDCARD_SOURCE, but either way, it did not appear in the output. I tried several variations of comment styles and locations without success. My suggestion is to support two types of description - A description in the same comment block as @start-group is a group-level description, and a standalone comment is a property-level description

    /** @start-group Special Metadata Names
     *  @description Wildcard and Override Settings are only used for Logging and Trigger control.
     */
    
    /** @description Overrides all metadata */
    public static final String WILDCARD_SOURCE = 'CodeControl_Default';
    /** @description Used if no matching metadata found */
    public static final String SYSTEM_WIDE_SOURCE = 'CodeControl_Override';
    /** @end-group */

would produce:

### Special Metadata Names
Wildcard and Override Settings are only used for Logging and Trigger control.

Overrides all metadata
* `SYSTEM_WIDE_SOURCE` → `String` 
 Used if no matching metadata found
* `WILDCARD_SOURCE` → `String` 
---

Or even better, allow in-line comments to appear in-line in the output:

    /** @start-group Special Metadata Names
     *  @description Wildcard and Override Settings are only used for Logging and Trigger control.
     */
    
    public static final String WILDCARD_SOURCE = 'CodeControl_Default'; /** @description Overrides all metadata */
    public static final String SYSTEM_WIDE_SOURCE = 'CodeControl_Override'; /** @description Used if no matching metadata found */
    /** @end-group */

Producing:

### Special Metadata Names
Wildcard and Override Settings are only used for Logging and Trigger control.

* `SYSTEM_WIDE_SOURCE` → `String` : Overrides all metadata
* `WILDCARD_SOURCE` → `String` :  Used if no matching metadata found
---

Alright, I'll stop flogging this same ticket with feature requests 😀 At this point I think the original issue is resolved, but I would recommend supporting javadoc-style for groups (e.g., /** @start-group Group Description */) to reduce confusion. Thanks for all of your support.

[cesarParra]

That all makes sense @jclark-dot-org. Thanks for all of the detail, I'll certainly look into all of that. I'll close this one and open an improvement issue to look into next.