himedlooff / doxray Goto Github PK

For example:

/* doxray
label: mikes pattern
options: [blockMarkup, collapseMarkup, showLess]
*/

I don't like nesting properties like this so when Doxray parses this it will move them to the top level like this:

/* doxray
label: mikes pattern
blockMarkup: true
collapseMarkup: true
showLess: true
*/

Issues pop up when there are no Dox-ray comments in a file. Parsing should at least return and empty array instead of nothing.

Hi @himedlooff - based on my success making this work with 11ty for css documentation, I decided to try and port my solution to document nunjucks macros:

const doxOptions = {
  regex: {
    njk: {
      opening: /^\{\#*\s*@docs[^\n]*\n/m,
      closing: /\#\}/,
      comment: /^\{\#\s*@docs[^*]*\#+(?:[^/*][^*]*\#+)*\}/gm,
      ignore: /^\{\#\s*@no-docs[\s\S]*/gm
    }
  }
};

fs.readdir(includeDir, (err, files) => {
  if (err) throw err;
  files.filter((file) => file.endsWith('.njk')).forEach((file) => {
    const docs = doxray([filePath], doxOptions);
  }
}

This returns an error:

Uncaught exception: (more in DEBUG output)
> Cannot read property 'comment' of undefined

`TypeError` was thrown:
    TypeError: Cannot read property 'comment' of undefined
        at Object.utils.getFileContents (/Users/miriamsuzanne/Sites/oddleventy/node_modules/doxray/utils.js:99:41)
        at Doxray.<anonymous> (/Users/miriamsuzanne/Sites/oddleventy/node_modules/doxray/doxray.js:68:42)
        at Array.forEach (<anonymous>)
        at Doxray.parse (/Users/miriamsuzanne/Sites/oddleventy/node_modules/doxray/doxray.js:64:7)
        at Doxray.run (/Users/miriamsuzanne/Sites/oddleventy/node_modules/doxray/doxray.js:49:17)
        at doxray (/Users/miriamsuzanne/Sites/oddleventy/node_modules/doxray/index.js:10:25)
        at files.filter.forEach (/Users/miriamsuzanne/Sites/oddleventy/content/_data/dox.js:35:20)
        at Array.forEach (<anonymous>)
        at fs.readdir (/Users/miriamsuzanne/Sites/oddleventy/content/_data/dox.js:31:51)
        at FSReqWrap.args [as oncomplete] (fs.js:140:20)

After some testing, it looks like the problem is in the getCommentType() switch, which forces any unknown extension into css. In fact, it works if I register my new regex patterns as css in the options object, and continue to run it on .njk files.

By default collapse the .less/.scss code to keep the pages shorter. Provide an override option if a pattern really wants to show it.

https://github.com/mtdowling/chag

This would be a breaking change.

So far I've worked on two templates to utilize Dox-ray data and found that the schema needs an update to allow for targeting specific files or tags.

Current Schema

array of files > array of doxray objects

[
    [{}, {}],
    [{}, {}]
]

Alternate Schema (that I've been using in a recent project)

object of files > array of doxray objects

{
    'filename.ext': [{}, {}],
    'filename.ext': [{}, {}]
}

Why the difference?

In Alternate Schema I needed to grab specific files and Current Schema does not support this out of the box. Other users might want to slice their data differently though, like using tags.

I wonder if there's a way to keep Current Schema because it's simple and provide a function that allows you to slice the data how you want it. This would mean that Doxray.parse() would have to create some mappings while parsing like:

{
    mappings: {
        files: {
            'filename1.ext': 0,
            'filename2.ext': 1
        },
        tags: {
            'colors': [data[0][1], data[1][0]],
            'variables': [data[0][0], data[1][1]]
        }
    },
    data: [
        [{}, {}],
        [{}, {}]
    ]
}

This would also mean updating the current schema. At the root we'd have .mappings and .data. .data is exactly the same schema from Current Schema.

Now if you wanted to access all of the data from filename1.ext you could do .mappings.files['filename1.ext']; If you wanted all docs tagged with colors you could do .mappings.tags.colors.

Questions

The files example can be built-in as we have all the data available to us, but we wouldn't know where to look in order to grab the tags or other mappings that users might want. Maybe there's a function or object you can pass to parse() that will tell Dox-ray what to look for.

How would files with the same name be handled?

You should be able to add a colorPalette property to any comment. If that comment contains color variables we can give templating access to these values so that you can loop over them and generate a color palette in your pattern library.

Dependency js-yaml@4 has breaking changes (https://github.com/nodeca/js-yaml/blob/master/migrate_v3_to_v4.md), but is pinned only as >=3.13.1 (https://github.com/himedlooff/doxray/blob/master/package.json#L32). This results in an error trying to use the now-removed yaml.safeLoad fn (https://github.com/himedlooff/doxray/blob/master/utils.js#L120) when js-yaml@4 is used.

> Error converting comment #1 to YAML. Please check for formatting errors.

`Error` was thrown:
    Error: Error converting comment #1 to YAML. Please check for formatting errors.
        at Object.utils.convertYaml (.../.yarn/cache/doxray-npm-0.10.0-a541a1e2bf-4a7d43c6be.zip/node_modules/doxray/utils.js:128:11)
        at Object.<anonymous> (.../.yarn/cache/doxray-npm-0.10.0-a541a1e2bf-4a7d43c6be.zip/node_modules/doxray/utils.js:63:26)
        at Array.forEach (<anonymous>)
        at Object.utils.parseOutDocs (.../.yarn/cache/doxray-npm-0.10.0-a541a1e2bf-4a7d43c6be.zip/node_modules/doxray/utils.js:59:8)
        at Doxray.<anonymous> (.../.yarn/cache/doxray-npm-0.10.0-a541a1e2bf-4a7d43c6be.zip/node_modules/doxray/doxray.js:71:34)
        at Array.forEach (<anonymous>)
        at Doxray.parse (.../.yarn/cache/doxray-npm-0.10.0-a541a1e2bf-4a7d43c6be.zip/node_modules/doxray/doxray.js:64:7)
        at Doxray.run (.../.yarn/cache/doxray-npm-0.10.0-a541a1e2bf-4a7d43c6be.zip/node_modules/doxray/doxray.js:49:17)
        at doxray (.../.yarn/cache/doxray-npm-0.10.0-a541a1e2bf-4a7d43c6be.zip/node_modules/doxray/index.js:10:25)

For example Less files are getting the type CSS. This is obviously wrong.

"Dox-ray" isn't growing on me as much as I thought it would. The idea behind it was that it was like an x-ray for your code that made documentation. The problem with "Dox" is that it could be confused with "documents", no megusta.

http://devdocs.magento.com/guides/v1.0/coding-standards/docblock-standard-javascript.html

This will make it more consistent, it's kind of confusing knowing when to use it and when to not.

Currently to merge files you need to pass a special argument that has a merge property. Dox-ray will compare objects and merge those which share that same property with the same value. We can ditch this argument and auto merge if the docs string is identical to others. See my update below.

The objects are confusing to talk about without clear terminology. The root is an array of files that are arrays of doc/code pairs. The code also has its own properties including code, which is confusing.

I'm wondering if it would be nice to have a closing Dox-ray comment which would basically allow you to ignore stuff in a file. For example:

/* doxray
    name: button, duh
*/
.btn { ... }

/* end-doxray */

/* Some other code you don't want to document */
...

/* doxray
    name: a different button or thing you want to document
*/
.btn__different { ... }

In the above example if you didn't have that ending Dox-ray comment /* end-doxray */ you'd get /* Some other code you don't want to document */ as part of the "button, duh" code. Boooo! Who wants that? No one.

Using https://github.com/keeganstreet/specificity

I'm planning to use this on an open-source project with a wide range of contributors. While /* doxray is a very clear regex pattern, I'm afraid it won't be immediately obvious what that is to new contributors. Any chance that could be a configuration option, or something more self-explanatory?

So you'd get a Dox-ray object that looks something like this:

{
  'docs': {},
  'main.css': '...', 
  'main.less': '...'
}

Or maybe code is an array of objects with filenames as keys:

{
  'docs': {},
  'code': [
    { 'main.css': '...' }, 
    { 'main.less': '...' }
  ]
}

Or maybe code is an array of objects with filename and code properties:

{
  'docs': {},
  'code': [
    { 'filename': 'main.css', 'code': '...' },
    { 'filename': 'main.less', 'code': '...' }
  ]
}

I like the first two because they are leaner but it seems like it would make things difficult to work with as you'd have to first figure out what the keys are in order to grab the code. Maybe there's an easy way to do that? The last one seems the easiest to work with.

The README mentions adding regex patterns as a customization, but (unlike processors) the regex block is not exposed as an option to easily pass in. Making the regex easily customizable might be a way to resolve #22, while also allowing new language additions.