Closed jclark-dot-org closed 2 years ago
@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
@cesarParra I did have v1 installed at one time, let me make sure there isn't a copy somewhere
@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.
Thanks for all of those details @jclark-dot-org . Its definitely an issue with the parser somewhere, I'll investigate
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?
@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.
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!
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{}
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.
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.
Running
@cparra/apexdocs@2.2.1
, I'm trying to use the new@start-group/@end-group
directives added in v2.1.0 (and thanks for that!), but they don't seem to work. Here's the start of my class:And here's the output:
I tried wrapping the last two constants in a group just in case, but it had no effect.