Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Annotate low-level scripting actions in various stores with JSDoc #1482

Closed
veggiesaurus opened this issue Jun 5, 2021 · 0 comments · Fixed by #2210
Closed

Annotate low-level scripting actions in various stores with JSDoc #1482

veggiesaurus opened this issue Jun 5, 2021 · 0 comments · Fixed by #2210
Assignees
Labels
code maintenance For issues relating to code maintenance and quality enhancement New feature or request

Comments

@veggiesaurus
Copy link
Collaborator

veggiesaurus commented Jun 5, 2021

Based on request in CARTAvis/carta#78 from @keflavich.

We need to have some form of documentation for the low-level scripting actions that are available. This will allow users to either utilise the debug execution feature on the frontend, or extend the high-level Python scripting interface.

I suggest we use JSDoc for this, as we can embed the documentation in the code and generate an API document in HTML reasonably easily.

As an example, the angus/jsdoc branch has the following for appendFile:

/**     
* @access public
* @async
* Appends a file at the given path to the list of existing open files
* @param path - path to the parent directory of the file to open, or of the file itself     
* @param {string=} filename - filename of the file to open     
* @param {string=} hdu - HDU to open. If left blank, the first image HDU will be opened     
* @return {Promise<number>} [async] the file ID of the opened file     
* */
* 
@action appendFile = (path: string, filename: string, hdu: string) => {
...

If we can document these functions well, and also extend the debug execution dialog into something more akin to a full scripting console, CARTA would become very extensible.

@veggiesaurus veggiesaurus added enhancement New feature or request code maintenance For issues relating to code maintenance and quality labels Jun 5, 2021
@veggiesaurus veggiesaurus self-assigned this Jun 5, 2021
@Kechil Kechil added this to the v3.0b-1 milestone Jun 23, 2021
@veggiesaurus veggiesaurus modified the milestones: v3.0b-1, v3.0b-2 Jul 26, 2021
@veggiesaurus veggiesaurus removed this from the v3.0b-2 milestone Nov 15, 2021
@veggiesaurus veggiesaurus added this to the v4.0-b1 milestone Aug 31, 2022
@veggiesaurus veggiesaurus removed this from the v4.0-b1 milestone Mar 1, 2023
@YuHsuan-Hwang YuHsuan-Hwang self-assigned this Jul 26, 2023
@github-project-automation github-project-automation bot moved this to New issue in CARTA Sep 19, 2023
@kswang1029 kswang1029 removed this from CARTA Dec 6, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
code maintenance For issues relating to code maintenance and quality enhancement New feature or request
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants