xalien95 / shortcuts-js Goto Github PK

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.

The Markdown component is based on Remarkable and Remarkable React Renderer for markdown rendering and on CodeMirror for the code blocks highlighting.

This issue lists all the features that need to be added to the renderer:

• Add support for automatic heading anchors
• Add support for external links

joshfarrant said:
As an aside, I'd also like to come up with a better documentation solution before hitting v1. The current docs are just ok and, while they're better than the previous solution (using jsdoc), they're still not fantastic. I get the feeling we're going to have to roll our own solution, as none of the out-of-the-box options are quite right. Hopefully we'll be able to base this custom solution on the JSON output from typedoc as that won't require any changes to the code, and typedoc is actually pretty good at what it does.

@joshfarrant, in the last couple of days I focused on this bit.
I saw that shortcuts.fun has been built with React, so I started to learn it.

I've almost named all the icon glyphs (joshfarrant#45) (and I discovered two unpublished ones that works too, red icons are the ones currently without names, I'm at 86.7%):

I also worked on an "Actions" page, in which all the actions should be listed following the sections in the Shortcuts app (I also found some minor errors in joshfarrant#6):

Since your site is under the following license:

Released under the GNU General Public License v3.0
© 2018 Josh Farrant

I need your approval to publish these documentation pages in this fork.