Improve descriptions when using grouping

cesarParra commented 2 years ago

Taken from https://github.com/cesarParra/apexdocs/issues/45#issuecomment-1127801984. See that issue for more details

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 @description does not 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

github-actions[bot] commented 2 years ago

This issue is stale because it has been open for 30 days with no activity.

github-actions[bot] commented 2 years ago

This issue was closed because it has been inactive for 14 days since being marked as stale.

jclark-dot-org commented 2 years ago

Please re-open; this was a feature request that hasn't been implemented yet. It's not stale, just not prioritized.

cesarParra commented 2 years ago

@jclark-dot-org Yup, done. Automation picked up this one so I might need to turn that off until I can get back to this.

Few busy weeks at work so haven't been able to dedicate too much time. I did start to take a look but it might take a bit to implement since I'd need to make some changes to the way apex docs are picked up to be parsed, since this would essentially represent a new concept that currently doesn't exist, and thus ignored during parsing.

github-actions[bot] commented 2 years ago

This issue is stale because it has been open for 30 days with no activity.

github-actions[bot] commented 2 years ago

This issue is stale because it has been open for 30 days with no activity.

github-actions[bot] commented 2 years ago

This issue is stale because it has been open for 30 days with no activity.

github-actions[bot] commented 1 year ago

This issue is stale because it has been open for 30 days with no activity.

github-actions[bot] commented 1 year ago

This issue is stale because it has been open for 30 days with no activity.

cesarParra commented 1 year ago

Added with release 2.11.0.

Groups can now be started and ended with /** */ comments. When starting the group, an @description can also be provided and that will be used as the group's description.

Any following /** */ after that will be used for the member (field, property, method, etc.) of the group, so it'd look like this:

    /**
     * @start-group This is a group
     * @description This is the group's description
     */

    /** @description Description for a member of the group */
    public static final String inGroup2;

    /** @description Description for the other member **/
    public static final String anotherInGroup2;

    /** @end-group */

cesarParra / apexdocs