DocBox commenting formatting

[lmajano]

@jcberquist Java Editors have two settings which are really helpful when formatting comments.

1. Ability to align parameter descriptions

This aligns the hint portions of the params. This is normal:

/**
* Startup a theme in the system, processes interceptions, modules, widgets, etc
*
* @name The name of the theme to activate
* @processWidgets Process widget registration on activation, defaults to true.
* @site The site id or object we are starting up this theme for
*/

This is the end result

/**
* Startup a theme in the system, processes interceptions, modules, widgets, etc
*
* @name                   The name of the theme to activate
* @processWidgets  Process widget registration on activation, defaults to true.
* @site                       The site id or object we are starting up this theme for
*/

2. Align @throws descriptions
3. Blank Lines

4. Generate

   on empty lines

5. Keep empty lines or not

[jcberquist]

I am not sure about implementing everything here, but I did try out getting parameter descriptions and @throws descriptions aligned in v0.17.1. There is a new settings for it: alignment.doc_comments.

[lmajano]

Wow that's great!

[lmajano]

Is there a way to get the spacing between them also? This is really a good visual of the doc code when params are tight together, @return and @throws are together. Basically like this:

/**
 * get Java FileInputStream for resource bundle
 *
 * @rbFilePath path + filename for resource, including locale + .properties
 * @path2 Another path
 *
 * @return java.io.FileInputStream
 * 
 * @throws ResourceBundle.InvalidBundlePath
 * @throws AnotherException
 */
public function getResourceFileInputStream( required string rbFilePath, path2 ){
}

[jcberquist]

Are you referring to the empty lines? e.g. this:

/**
 * get Java FileInputStream for resource bundle
 * @rbFilePath path + filename for resource, including locale + .properties
 * @path2 Another path
 * @return java.io.FileInputStream
 * @throws ResourceBundle.InvalidBundlePath
 * @throws AnotherException
 */
public function getResourceFileInputStream( required string rbFilePath, path2 ){
}

would become this:

/**
 * get Java FileInputStream for resource bundle
 *
 * @rbFilePath path + filename for resource, including locale + .properties
 * @path2 Another path
 *
 * @return java.io.FileInputStream
 * 
 * @throws ResourceBundle.InvalidBundlePath
 * @throws AnotherException
 */
public function getResourceFileInputStream( required string rbFilePath, path2 ){
}

[lmajano]

Yes Luis Majano CEO Ortus Solutions, Corp 1-888-557-8057 909-248-3408 www.ortussolutions.com Support Open Source: www.patreon.com/ortussolutions Linked In: https://www.linkedin.com/pub/3/731/483 Social: twitter.com/ortussolutions | twitter.com/lmajano

…

On Dec 7, 2021, 1:25 PM -0600, John Berquist ***@***.***>, wrote: Are you referring to the empty lines? e.g. this: /** * get Java FileInputStream for resource bundle * @rbFilePath path + filename for resource, including locale + .properties * @path2 Another path * @return java.io.FileInputStream * @throws ResourceBundle.InvalidBundlePath * @throws AnotherException */ public function getResourceFileInputStream( required string rbFilePath, path2 ){ } would become this: /** * get Java FileInputStream for resource bundle * * @rbFilePath path + filename for resource, including locale + .properties * @path2 Another path * * @return java.io.FileInputStream * * @throws ResourceBundle.InvalidBundlePath * @throws AnotherException */ public function getResourceFileInputStream( required string rbFilePath, path2 ){ } — You are receiving this because you authored the thread. Reply to this email directly, view it on GitHub, or unsubscribe.

[jcberquist]

Alright, I have tried making this a lot more opinionated. It will now group @params and @throws together, with empty lines between the groups. It might be too opinionated now 😀 .