Ideas for flexible formatting

[tomek-he-him]

How about making doxme formatting customizable?

For example, with a predefined readme structure like

# project name
## installation
## usage
## api
{{ doxme output }}
## license

…one would want function names to be prepended with ### instead of ##.

How can we do it?

I have two ideas:

1) Accept custom string-based templates

doxme([/* dox output */]
  , { readme: false
    , formatting:
      { functionName: "### %s"
      }
    }
  );

And in the command line:

$ ... | doxme --formatting='{"functionName": "### %s"}'

– or (this I like better):

$ echo '{"readme": false, "formatting": {"functionName": "### %s"}}' > .doxme.json
$ ... | doxme

Pros:

• Easy to implement – the templating is already built in :)
• JSON-serializable config

Cons:

• Not very flexible – e.g. what when we have %s twice, and only want the second one?
• If the tool grows, we can quickly end up with dozens of variations of one template (like functionName, functionNameWithParameters, functionNameWithRepetitiveParameters etc.)

  2) Accept custom formatting functions (this one I like a lot better)

doxme([/* dox output */]
  , { formatting:
      { functionName: function (name, parameters) {
        return ("### " + name + (parameters
          ? "(" + parameters.join(", ") + ")"
          : ""
          ));
        }
      }
    }
  );

In the command line:

$ echo 'module.exports = {formatting: {functionName: function (...' > .doxme.js
$ ... | doxme

Pros:

• A lot more flexible
• "do one thing, and do it well" – templating isn't necessarily "the thing"
• We could enable the user to parse tags not supported by us – for example through a head(tags) and tail(tags) formatting function:

{ tail: function (tags) {  // Parse the tag @deprecated
  return (
    ( tags.some(function (tag) {return (tag.type == "deprecated");})
    ? "\n_Deprecated_\n"
    : ""
    ));
  }
}

Cons:

• One could argue that it's more difficult to setup through the CLI (though I wouldn't agree)

  Why would we do it?

Adherence to the Unix "do one thing and do it well" principle is what drew me to doxme in the first place :) Markdox tries to replace dox, so it chokes with non-flexibility.

But Unix programs not only "do one thing" but also "do it well". As I understand it, it means that they are very flexible.

Let's make doxme like that :)

[tmcw]

How about making doxme formatting customizable?

I'm not very convinced that there's a concrete use case for this: re-ordering sections? h2s instead of h3s? Seems like reasonable defaults cover 90+% of cases.

[tomek-he-him]

I'm not very convinced that there's a concrete use case for this: re-ordering sections? h2s instead of h3s?

• Or rather h4s instead (sorry, I've made a mistake in my example)
• Support for rarely-used or custom tags
• Non-standardized conventions
• I'm sure there's way more

My concrete problem at the moment is the third. I'm looking for a good way to document a heavily overloaded function. Standards don't work well in this case, as you can read here: https://groups.google.com/forum/#!searchin/jsdoc-users/overloaded .

Seems like reasonable defaults cover 90+% of cases.

Well, if you look at different readmes in github, you'll hardly ever find two structured in the same way. Every developer has their own conventions and opinions.

Reasonable defaults are great for a start, I agree in that. But "for a start" really means "only up to a point".

[tomek-he-him]

@tmcw for reference, here's the case I'm talking about: http://npm.im/parametric-svg – see for yourself.

In the case of doxme's readme, the defaults really work great. But in my project the outcome isn't too readable.

[tmcw]

Couldn't you use jsdoc's multiple parameter type syntax for this?

[tomek-he-him]

I've tried. But in my case it would be „If you supply an SVGSVGElement, it will be treated as a ... . The second parameter is then optional and will mean ... . If you supply an SVGElement, it will be understood as ... . The second parameter is then required ...” etc. Hard to document and very hard to understand.

Think how, say, any jQuery function could be documented with multiple parameter syntax.

[tmcw]

The 'just document it multiple times' convention seems to work for me.

Basically customizing doxme's formatting doesn't really make sense to me: it basically just is a template and nothing more. swapping out the formatting means swapping out the whole thing, and at that point... just fork

[tomek-he-him]

Yup, and that's what I actually did.

But I do see what you mean since I looked closer at the code.

Alright then. As there doesn't seem to be anyone else backing my idea out there, I'm closing.