Default value for action parameters in TypeDoc

xAlien95 commented 5 years ago

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

const base64Encode = (
  options: {
    /** The encoding mode to use */
    encodeMode?: WFEncodeMode,
    /** The line break mode to use */
    lineBreakMode?: WFSerialization | WFBase64LineBreakMode,
  },
): WFWorkflowAction => {
  const {
    encodeMode = 'Encode',
    lineBreakMode = 'Every 76 Characters',
  } = options;

  return {
    WFWorkflowActionIdentifier: 'is.workflow.actions.base64encode',
    WFWorkflowActionParameters: {
      WFEncodeMode: encodeMode,
      WFBase64LineBreakMode: lineBreakMode,
    },
  };
};

AFTER

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,
  },
});

Alternatively, JSDoc-ish @default tags could be applied on the options type:

const base64Encode = (
  options: {
    /** The encoding mode to use */
    /** @default 'Encode' */
    encodeMode?: WFEncodeMode,
    /** The line break mode to use */
    /** @default 'Every 76 Characters' */
    lineBreakMode?: WFSerialization | WFBase64LineBreakMode,
  },
): WFWorkflowAction => {
  const {
    encodeMode = 'Encode',
    lineBreakMode = 'Every 76 Characters',
  } = options;

  return {
    WFWorkflowActionIdentifier: 'is.workflow.actions.base64encode',
    WFWorkflowActionParameters: {
      WFEncodeMode: encodeMode,
      WFBase64LineBreakMode: lineBreakMode,
    },
  };
};

@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:

const addToReadingList = (): WFWorkflowAction => ({
  WFWorkflowActionIdentifier: 'is.workflow.actions.readinglist',
  WFWorkflowActionParameters: {},
});

I'm open to suggestions and different approaches.

joshfarrant commented 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}

xAlien95 commented 5 years ago

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.

joshfarrant commented 5 years ago

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?

xAlien95 commented 5 years ago

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:

add default params and @action, @section, @icon tags to all actions
rename the actions I wrote in the last comment
add WFSerialization/Variable to all action params (that's something I will do with the 3rd and last pull request regarding the variables addition)
- add all the tests with the WFSerialization/Variable parameters types
edit CONTRIBUTING.md with the steps to follow when adding all the required tags

EDIT: 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. 😁

joshfarrant commented 5 years ago

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.

xAlien95 commented 5 years ago

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.

joshfarrant commented 5 years ago

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 => {...};

joshfarrant commented 5 years ago

Modified destructuring is in, as are the name changes @xAlien95.

xAlien95 commented 5 years ago

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

xAlien95 / shortcuts-js

Default value for action parameters in TypeDoc #3

BEFORE

AFTER