Open xAlien95 opened 5 years ago
Totally agree with you @xAlien95, I much prefer the first approach. I’m happy to go through and make these changes, if you’d prefer.
Sent with GitHawk
Totally agree with you @xAlien95, I much prefer the first approach.
It may be eventually reduced from this:
const base64Encode = (
{
encodeMode = 'Encode',
lineBreakMode = 'Every 76 Characters',
}: {
/** The encoding mode to use */
encodeMode?: WFEncodeMode,
/** The line break mode to use */
lineBreakMode?: WFSerialization | WFBase64LineBreakMode,
},
): WFWorkflowAction => ({
WFWorkflowActionIdentifier: 'is.workflow.actions.base64encode',
WFWorkflowActionParameters: {
WFEncodeMode: encodeMode,
WFBase64LineBreakMode: lineBreakMode,
},
});
to this:
const base64Encode = ({
encodeMode = 'Encode',
lineBreakMode = 'Every 76 Characters',
}: {
/** The encoding mode to use */
encodeMode?: WFEncodeMode,
/** The line break mode to use */
lineBreakMode?: WFSerialization | WFBase64LineBreakMode,
}): WFWorkflowAction => ({
WFWorkflowActionIdentifier: 'is.workflow.actions.base64encode',
WFWorkflowActionParameters: {
WFEncodeMode: encodeMode,
WFBase64LineBreakMode: lineBreakMode,
},
});
but it's just aesthetics.
I’m happy to go through and make these changes, if you’d prefer.
Thank you, it would be very welcome. There should be a few more edits to do, if I remember correctly, regarding the function names (https://github.com/joshfarrant/shortcuts-js/issues/26):
getContentsOfUrl()
to getContentsOfURL()
getCurrentIpAddress()
to getCurrentIPAddress()
runJavascriptOnWebPage()
to runJavaScriptOnWebPage()
showInItunesStore()
to showInITunesStore()
url()
to URL()
urlEncode()
to URLEncode()
I have an unrelated question: should the TypeDoc generated html page remain, or do we have to provide a completely custom React-based "API page"?
I'm asking this because of the @action
, @section
and @icon
custom tags I added in this fork. With the TypeDoc generated html page, we either have to place those tags on the bottom or to use a plugin.
I have an unrelated question: should the TypeDoc generated html page remain, or do we have to provide a completely custom React-based "API page"?
I think the end-goal would be to have custom docs which remove the need for the generated typedoc docs altogether, if that works for you?
I'm just looking at converting the default params to the new format, currently my complete base64encode.ts
action looks like this:
import { withActionOutput } from '../utils';
import Variable from '../interfaces/Variable';
import WFBase64LineBreakMode from '../interfaces/WF/WFBase64LineBreakMode';
import WFEncodeMode from '../interfaces/WF/WFEncodeMode';
import WFWorkflowAction from '../interfaces/WF/WFWorkflowAction';
/**
* Encodes or decodes text or files using Base64 encoding.
*
* ```js
* base64Encode({
* encodeMode: 'Encode',
* lineBreakMode: 'Every 76 Characters',
* });
* ```
*
* @action Base 64 Encode
* @section Actions/Scripting/Files
*/
const base64Encode = (
{
encodeMode = 'Encode',
lineBreakMode = 'Every 76 Characters',
}: {
/** The encoding mode to use */
encodeMode?: WFEncodeMode,
/** The line break mode to use */
lineBreakMode?: Variable | WFBase64LineBreakMode,
},
): WFWorkflowAction => ({
WFWorkflowActionIdentifier: 'is.workflow.actions.base64encode',
WFWorkflowActionParameters: {
WFEncodeMode: encodeMode,
WFBase64LineBreakMode: lineBreakMode,
},
});
export default withActionOutput(base64Encode);
export const icon = 70;
Other than the default params, is there anything else you'd like me to change whilst going through the files at the same time @xAlien95? I'm making these changes from my documentation
fork, which already includes a few changes I made when I started looking at the documentation generation a few weeks ago. Would you like me to add @action
and @section
tags to all actions? Also, would you like me to export an icon
from all actions?
I think the end-goal would be to have custom docs which remove the need for the generated typedoc docs altogether
Great.
You can add the @icon
tag too. You can download and locally run the last version of the docs
branch, action icon names are listed on localhost:3000/docs/contributing/action-icons
.
To help you speed up the process, you can take a look at this gist: icon names are on the left, action names on the right.
As for the sections, I used >
as separator because some section names may eventually contain texts like Convert to HTML/XHTML
or Code/Decode CSV Table
. More over there are apps with slashes in their names (e.g. Google I/O).
I also used the following convention for unnamed groups (the same ones where you added _
if I remember correctly):
@section Actions > Scripting >
My parser does a .split(/\s?\>\s?/)
, so that section already gives a blank ''
group name.
import { withActionOutput } from '../utils';
import WFBase64LineBreakMode from '../interfaces/WF/WFBase64LineBreakMode';
import WFEncodeMode from '../interfaces/WF/WFEncodeMode';
import WFSerialization from '../interfaces/WF/WFSerialization';
import WFWorkflowAction from '../interfaces/WF/WFWorkflowAction';
/**
* Encodes or decodes text or files using Base64 encoding.
*
* ```js
* base64Encode({
* encodeMode: 'Encode',
* lineBreakMode: 'Every 76 Characters',
* });
*
* @action Base64 Encode
* @section Actions > Scripting > Files
* @icon Scripting
* ```
*/
const base64Encode = (
{
/** The encoding mode to use */
encodeMode = 'Encode',
/** The line break mode to use */
lineBreakMode = 'Every 76 Characters',
}: {
encodeMode?: WFEncodeMode,
lineBreakMode?: Variable | WFBase64LineBreakMode,
},
): WFWorkflowAction => ({
WFWorkflowActionIdentifier: 'is.workflow.actions.base64encode',
WFWorkflowActionParameters: {
WFEncodeMode: encodeMode,
WFBase64LineBreakMode: lineBreakMode,
},
});
export default withActionOutput(base64Encode);
I think that it's better to make these changes on the joshfarrant/master
branch. This way contributors can already base new actions on the "new format". Moreover I will just need a rebase to get the updated actions.
Essentially, what needs to be done is the following:
@action
, @section
, @icon
tags to all actionsWFSerialization/Variable
to all action params (that's something I will do with the 3rd and last pull request regarding the variables addition)
WFSerialization/Variable
parameters typesEDIT: in the last commit I added the Lightroom app icon, since now its action has come back in Shortcuts. You should edit https://github.com/joshfarrant/shortcuts-js/issues/6 and add it back.
There's also a misspelling in Sharing > WhatsApp > Send Mesage via WhatsApp
. 😁
The @action
, @section
and @icon
tags are all currently available in my documentation
branch. I ended up writing a script to generate the tags automatically, so there may well be some mistakes (especially with @section
, I need to revisit that...) but, for the moment, there's something there at least.
Next, I'll move on to destructuring the options
param, and look at the best way to correct the incorrect @section
tags.
To help you speed up the process, you can take a look at this gist: icon names are on the left, action names on the right.
Cool @joshfarrant! I noticed you didn't use the gist I provided (https://gist.github.com/xAlien95/2f4faa8413b30039ed591f550a6a4b20) in my previous comment. It has all the icon names and a representation of all the sections. Using that you'll come with the right sections.
Next, I'll move on to destructuring the
options
param
I filed a bug on TypeDoc (https://github.com/TypeStrong/typedoc/issues/957) and provided a solution. Without my solution, referenced types won't work in the output json and comments have to be added this way:
const createAlarm = (
{
/** The alarm active state */
active = true,
/** The alarm time */
time = '',
/** Whether the alarm should repeat on certain days */
repeat = [],
}: {
active?: boolean | Switch,
time?: string,
repeat?: Frequency[],
},
): string => {...};
With my fix, comments should be added this way:
const createAlarm = (
{
active = true,
time = '',
repeat = [],
}: {
/** The alarm active state */
active?: boolean | Switch,
/** The alarm time */
time?: string,
/** Whether the alarm should repeat on certain days */
repeat?: Frequency[],
},
): string => {...};
I'll see if I can write a plugin to temporarily fix that issue for us.
Fantastic, thanks!
I've run through the gist and fixed the incorrect @section
tags. Again, this was scripted so there may be the odd mistake, but running through them all they all look pretty good :+1:
Next, I'll take a look at the destructuring (+ comments) in this format:
const createAlarm = (
{
active = true,
time = '',
repeat = [],
}: {
/** The alarm active state */
active?: boolean | Switch,
/** The alarm time */
time?: string,
/** Whether the alarm should repeat on certain days */
repeat?: Frequency[],
},
): string => {...};
Modified destructuring is in, as are the name changes @xAlien95.
Great, glad it helped 😄
Again, this was scripted so there may be the odd mistake, but running through them all they all look pretty good 👍
When the .shortcut to .js converter will be ready, I’ll edit each file and look for errors, so no problem. Each action will probably have a direct and inverse function:
const createAlarm = ...
const inverse = (WFAction): object => ...
export default createAlarm
export inverse
Currently, TypeDoc is not able to get default values for action parameters and a small refactoring of either the comment bits or the functions themselves has to be done in order to parse them.
I came up with the following solution:
BEFORE
AFTER
Alternatively, JSDoc-ish
@default
tags could be applied on the options type:@joshfarrant, your thoughts? Personally, I prefer the first approach for both the fact that it's more compact and it resembles how actions without parameters are currently written:
I'm open to suggestions and different approaches.