Allow code blocks in doc strings

[allforabit]

Issue description or question

I'm looking for a way to run functions in a module without adding console logs or other code. I was thinking a nice way of doing this could be through code blocks contained in doc strings as this is a nice place to put example usage. By the way if there are other ways that this can be done I'd love to hear it. The best I can thing of at the moment is putting it inside a dev environment check statement so that it won't be included in production (and of course just manually removing when I don't need them).

Sample code

/**
 *
 * ```typescript
 *  myfunc(1, 2);
 * ```
 */
const myFunc(a, b) => a + b

Code editor version

Visual Studio Code v1.?

OS name and version

Windows

[smcenlly]

Can you explain what you want/need to do this so that we can understand your use case vs. how you'd like to see it implemented at a technical level? Why do you need this functionality? For example, are you mocking an existing library that isn't available in the context of when Quokka runs?

As an aside, you can do something like this:

Example

const myFunc = (a, b) => a + b;

1; /* ? 
  myFunc(1, 2) 
*/

What's happening in the example is we're emitting valid JavaScript code, 1;, with a live value beside it. In the live value, we're then executing the myFunc() function. In Quokka, you'll see output as shown below (see the value displayed at the top of the comment):

You're limited in what you can execute in this case (single function call only, console.logs don't work, and a few other limitations).

[allforabit]

Thanks, that looks nice. I just want a way to run a function with some sample arguments without adding code I'll need to remove before pushing to production. I thought a nice place for this would be the doc comment block above it. Although have to say it's not a big deal and would just be a nice to have. It works pretty great as it is!

[smcenlly]

OK - thanks. If I understand you correctly, what we've provided above is a decent enough workaround for now? The 1 in the code doesn't actually do anything, even though it's valid JavaScript.

In terms of what we ourselves do, we prefer not to have dev-time Wallaby/Quokka code artifacts in our code, which is why we have introduced Live Value Display features such as Show Value and more recently the ability to simply select an expression/value to output the result. Of course, if you want something that persists across all Quokka executions, you'll still need to have persistent comments in your code.

[allforabit]

Yes live values are great and can cut down a lot on the need for additional artifacts. I think some minimal code is unavoidable though. The things I'm trying to run are small internal functions of a module that I don't really want to export or test directly. I use wallaby for running the exposed functions. It's just that sometimes I'm trying to focus on a small internal function and it feels awkward to get at. A nice feature of wallaby is it encourages a virtuous cycle of writing tests to try out different features. I'm trying to achieve something similar with quokka so that the additional artifacts I create are actually useful, in this case as documentation. To that end I've made a vs code snippet similar to the following:

//#region examples
if (process.env.NODE_ENV !== "production") {
  myFunc(9) /*?*/;
}
//#endregion

I'm placing it just below the function in question. The region tag means it can be hidden easily in vs code and the environment check will make webpack exclude from the production build.

[josuamanuel]

It would be nice if it could get done without the inclusion of any live code. It looks a little bit buggy the need to include the number and specially the limitations: single function call only, console.logs...

1; /* ? myFunc(1, 2) */

I tend to add comments with hardcoded data structures to show the intent of data flow and transformation in Ramda functional programming style. The hardcoded comment examples shows the intention better. The problem is that we know that documentation gets outdated if team members are not consistent... having a live evaluation results... without impacting Production code to demonstrate uses... OMG....

i think it would be a really nice feature.