api section syntax

[yoshuawuyts]

originally posted in standard/standard#141 (comment)

Something that this module could additionally do is lint the way interfaces are defined in the API section. Everyone seems to do it differently, and having some consistency would be great. Just to display some of the flavors:

browserify

b.plugin(plugin, opts)

Register a plugin with opts. Plugins can be a string module name or a
function the same as transforms.

plugin(b, opts) is called with the browserify instance b.

For more information, consult the plugins section below.

virtual-dom

Patch operations

patch(rootNode:DOMNode, patches:PatchObject) -> DOMNode newRootNode

Once we have computed the set of patches required to apply to the DOM, we need a function that can apply those patches. This is provided by the patch function. Given a DOM root node and a set of DOM patches, the patch function will update the DOM. After applying the patches to the DOM, the DOM should look like the new VTree.

from2

stream = from2.obj([opts], read)

Shorthand for from2({ objectMode: true }, read).

[zcei]

I kinda like the blade API style

• signature as a heading
• short description
• list of parameters / options
• (added) returns to clearly point out the result

Looks like this:

blade.compile(string, [options,] cb)

Compiles a Blade template from a string.

• returns: The compiled string, if options.sync is set
• string - a string of Blade
• options include:
  • filename - the filename being compiled (required when using includes or the cache option)
  • cache - if true, the compiled template will be cached (defaults to false)

For everything that's too huge to get described this way probably should have their own wiki / api.md

[junosuarez]

I'm -1 for including this in standard-readme, just because I don't think we'll ever be able to reach consensus. I think coming to some agreement on the rough outline (section headers, etc) of a readme would be enough of a step forward.

[terinjokes]

My preference would be the format of virtual-dom with jsig. The section titles are human readable, and the jsig gives a very accurate and concise type description of the API.

But I agree with @jden, that we'll probably paint many bikesheds here.

[zcei]

But it also causes the biggest headaches all the time.

Personally I don't want to regulate all API documentation, but the one existing in the readme.
A clear and sane layout speeds up the process of reading a lot.

On the other hand jsig slows down development, especially for rather small projects.
Here we'd try to square the circle, as a "standard-documentation" - I'm pretty sure a lot smart heads failed at this.

[tunnckoCore]

I think standard-readme should only ensure there have API section/block (for that i think it should be optional), nothing more, nothing less, until project is so small that there's no sense to have that section (like single method, just module.exports = function () {})- in that cases most useful section is usage/example and simple description and maybe param types, we shouldn't force people how to style them. There's a lot documentation/api generators, even one https://github.com/verbose/verb which generate api from code comments from given filepath or directory with files that (module.)exports

https://github.com/jonschlinkert/micromatch and https://github.com/jonschlinkert/utils are also generated with verb, without any hand work.

[yoshuawuyts]

I agree with @zcei. Having consistency is more important than reaching consensus, I believe that is the same philosophy that drove standard into existence (and tons of bike shedding with it, but guess that's inevitable).

I'm quite fond of how browserify and from2 define their api sections, having a preference for a non-monospace font in the headers (more readable imo). The blade approach seems similar, though I find the unwrapping of arguments to be slightly verbose.

jsig looks interesting, in particular the anonymous signatures. Not sure I'd prefer it over the browserify / from2 syntax because it's a bit verbose, but definitely worth considering / borrowing concepts from.

So far I've yet to see any good documentation generators, most generators seem to generate documentation for machines, not humans. I find the docs for micromatch to be slightly overwhelming to be fair.

[tunnckoCore]

I find the docs for micromatch to be slightly overwhelming to be fair.

Mm yea, not good example. But utils is generated fully with verb - from TOC to the license line, copyright line, api, related projects and etc. Verb is fully configurable and you can define custom templates how to display API and other things. What can you say for utils README?

[zcei]

I like the idea of using a jsig subset, basically it'd look like this:

• argument names should be self-explanatory, then no annotation is needed
• callback arguments may have an declarative name
• arguments which need further explanation without type (avoid redundancy)
• optional arguments with squared brackets, encapsulates preceding comma
• ? (required || optional) description after function signature
• (optional) Example section

blade.compile: (bladeTemplate:String[, options], cb) => void

Compiles a Blade template from a string.

• cb: (Error, compiledHTML:String) => void
• options: Object
  • filename: String required when using includes or the cache option
  • cache: Boolean defaults to false

Example:

blade.compile('h1 foo\n\t| sum text', function(err, html) {
  console.log(err || html);
});

[mattdesl]

Worth noting: not all modules that will use standard-readme will also need to lint the API section. For example, any glslify modules:
https://github.com/stackgl/glsl-perturb-normal#vec3-perturbed--perturbvec3-m-vec3-n-vec3-v-vec2-texcoord

[zcei]

A try to revive: I've been quiet for a long time, but the issue still bothers me.

What I recently found is rtype and I'm thinking about using its function signatures for an easy-to-read, yet standardized API section.

They are clearly intended for developers, but still it would be able to parse a decent documentation for trickier projects.

And finally: Yes, I know it's a dev draft, but think it's the same as this project: It deserved to be pushed forward :)

[wooorm]

Cool, @zcei.

I was wondering, are there already actionable points for this? I may be able to work on this but I'm not yet sure what's decided.

[zcei]

As the rtype part is currently a RFC, I think there are more actionable items on their repo.

We basically need some tooling to ensure that the function signatures are syntactically correct.

In terms of "what's decided" I would wait for @fibo to bring up his arguments (he opened #5, because he wrote an article about tiny packages and we have a good overlapping in the readme part)

If he can't convince me, I will decide for rtype (mainly because I don't like JSDoc)
How the actual code comments -> documentation -> excerpt for readme will work, that's yet to decided

[fibo]

Something that matches with dox would be nice

API

foo(bar)

get the bar count

If you want to know the bar count you should use this function.

var countBars = foo(bar)
console.log(countBars) // 12

@api	private
@param {String}	bar	Lorem ipsum digitorum
@returns {Number}	count

---

Follows the markdown code

## API

<a name="foo"></a>
### `foo(bar)`

> get the bar count

If you want to know the bar count you should use this function.

```
var countBars = foo(bar)
console.log(countBars) // 12
```

||||
---|---|---|
|`@api`|**private**|
|`@param {String}`|bar| Lorem ipsum digitorum
|`@returns {Number}`|count|

[wooorm]

Oh, darn, I see I posted this here, this should’ve been #1 (regarding the if anything/section is already decided).

Regarding API syntax, I’d opt for the third example mentioned above (from2), with the following reasoning:

• It’s very intuitive, if you can read JavaScript, you can understand that syntax;
• It’s preferred by feross (safe-buffer, webtorrent, etc.) and other “high profile” standard users (mafintosh, multicast-dns; maxogden, concat-stream), etc.
• It’s different from browserify in one small superior aspect, namely, wrapping in inline code (ticks).
  Not only does that look better, it’s also because it’s possible for the optional operator in signatures to clash with markdown definitions. For example, the following code:

# b.plugin([plugin], opts)

[plugin]: http://example.com

Yields:

b.plugin(plugin, opts)

Thus, escaping of [ may or may not be needed. The alternative is code ticks:

# `b.plugin([plugin], opts)`

[plugin]: http://example.com

Yields the, in my opinion, great looking:

b.plugin([plugin], opts)

---

I’d also suggest not to use the dox example mentioned above by @fibo, it’s quite verbose, stemming from the fact that it’s a jsdoc parser resulting in all those (superfluous) tags (for example, if something is private it shouldn’t be in an API section, right?)

[tunnckoCore]

What about @jonschlinkert's readme styles? I mean, we almost all use jsdoc and it is easy to parse and already have good tools for parsing and outputing good documentation.

There's a lot of examples, he have 1000+ npm packages and huge amount of github repos and projects which already use almost completely finished tools for doing the job and do it great. That's why he is big name in our community and there's no point against that.

https://github.com/node-base/base#api
https://github.com/jonschlinkert/template#api
https://github.com/jonschlinkert/scaffold#api
https://github.com/verbose/verb/tree/dev#api

Why we should use jsdoc? Because it leads to good and enough in-source documentation docblock comments from which can be generated good human documentation and readmes/sites.
He already have the tools and projects needed to do the job. (from small to complex).

I can't think for better documentation than that (for example) source doc / human doc - it have and says everything, and give answers to many questions - what are the params, what are their types, description of the method, description of every param, and optionally you can add little example in the source code.

JSDoc is perfect for code documenting. Those tags are not superfluous.

---

And no, this isn't promotion of Jon Schlinkert and his tools and packages. For me, it is the best way to do the job and have perfect balance between well-formated source code comments and human-readable, human-understandable and easy api and documentation.

---

Btw, shown examples are useful only for one type of humans - users, users which just will use the given package, but not the developers, not those people that read and contribute to the code. And one of the greatest things about tools created by and used by Jon is that all documentation is linked (out of the box) - it remainds me to "two-way data-binding" -- for README to source and source to README.
This linking helps (a lot!). What about if one of above signatures and example in such style not answer the user? What about if package is big and with huge source and huge amount of files? - user should invest huge time in scrolling and searching the thing that he want to clear in his mind - yea, maybe it will use the github search but.. nah.

---

Standards. Standards should be FROM anyone, not from few people in the community and their prefs and styles. Yea, they also are big and valuable community members. And the reason that I'm strongly behind Jon's style is that his tools use JSDoc and there's a lot more people that use JSDoc, then few devs that invent new style documenting (in my mind popups @yoshuawuyts style, sorry man - i understand your documentation and source code comments, but i dont think that's the way :) )

Cheers,
Charlike! 🍻

[wooorm]

@tunnckoCore I don’t think whether or not JSDoc should be used is of interest to standard-readme. The reason JSDoc was first mentioned was because it can do things similar to rtype, but the other way around doesn’t hold true (you cannot use jsdoc to document a function signature). EDIT: In an API section

The reason I later mentioned JSDoc, was because the example provided above (dox, generated from JSDoc) was pretty verbose, e.g., including @api: private in the docs. I don’t think a function, which has @api private in its JSDoc, should be included on the READMEs API section. That is superfluous.

Note: I love JSDoc, I use it all the time and my code is literally littered with the stuff.

Thanks for bringing up Jon’s repos, he sure has contributed a lot to the community, and he definitely has a very nice style of documenting stuff (plus he’s a great guy). However, it’s very customised to his liking (I haven’t seen much like it by other people). That’s fine, I have my own signature style too, but I’d like to opt for a more “standard” style for something which is called “standard-readme” and affiliated with “standard”.

On a side node: we should think more about what the people using standard want / use, as a project called “standard-readme” is weird when “standard” people don’t like the enforced style.

[tunnckoCore]

@wooorm I can agree with you. And yea, have reason in your last paragraph.
But if i should go religious.. the word "standard". Initially I was not agreed with standard, because it removes semicolons, but actually accept it after some time all over my repos. Then popups semi-standard, then Sindre's xo. And I think all this is the biggest problem of our community - "standards", those standards. Ones dont want to use TJ's packages, another dont want to use Sindre's, another Gulp's and etc.
But yea, okey, maybe it's normal and can understand it, because all of us are different persons. But for me, this should stop somewhere sometime :)

However, it’s very customised to his liking (I haven’t seen much like it by other people).

Yea, but they at least use jsdoc and it won't be hard to just use some tool all over their projects.

Cheers,
Charlike! 🍻

[wooorm]

Regarding your last two points (and please don’t edit comments without stating what you changed) of #3 (comment):

• links to source code can be added to every style mentioned earlier, e.g., browserify, virtual-dom, from2, safe-buffer, webtorrent, multicast-dns, concat-stream.
• Your last point, inventing new styles, is exactly what I’m advocating against (as my previous comment noted, this has nothing to do with JSDoc). If I compare Jon’s (very nice) style to Feross’ style (also nice) of documenting function signatures, the latter looks more familiar and more like other README API sections.

And regarding your last #3 (comment), sure, but this project is called standard-readme and not sindre-readme or tj-readme 😉

[zcei]

I definitely didn't want to introduce rtype as the documentation tool of choice.
It was really just for the function signature, as it's quite near to ES2015+ / a more functional style of js.

For extensive documentation I also like JSDoc, but just not for "simple annotations" or, as said, function signatures.

The from2 documentation has a really clean look, plus I like the idea, that "high-class standard users" would be automatically on the same track, especially when they already have kind of an aligned readme style.
But these headings should have a few more levels (2-4x #), otherwise it's like a visual punch in the face 😉

[wooorm]

Agreed regarding the size. In real usage (yes I’ve done research), API signatures start at level three, as a README has one major heading (name of project), a secondary heading named API, thus the signatures start at level three:

b.plugin([plugin], opts)

Which comes down to a real-estate of 34 vertical CSS pixels, which looks okay!

[zcei]

Very nice outcome of your research, can just agree!

I started extracting the consensus of #1 into rules.md.
As you're the creator of remark, it would be cool, if you could provide a litte boilerplate on how to build a linting tool for it, as this would be the next action item.
Maybe a small PR when there's time? Then I can continue and build a first useable tool.

In the meantime I'll check out some of your mentioned repositories to get a feeling how the API style behaves out in the wild.

[wooorm]

Okay, I’ll outline some actionable things soon in a separate issue.

[fibo]

@wooorm : yes you are right, @api private does not make sense, it was a mistake.

I think that

b.plugin([plugin], opts)

is ok, and could have an optional heading forced

<a name="b.plugin"></a>

this is stolen from levelup documentation.

About the table with params and returns, I think is a good idea to list params explicitly. It helps readability.

[wooorm]

@fibo I definitely agree that parameters should be explicitly listen! However, not so sure over tables. In my opinion, that quite rigorous style is not needed for every README. Foe example, the aforementioned from2 only has two parameters which I think come across just fine from a list.

[jonschlinkert]

A readme is more than API documentation, it's metadata for and about a project. Oftentimes a readme contains everything BUT the API documentation - like when the docs are hosted on gh-pages. Any standard that the community backs should be much more focused on the overall sections, expected metadata, and readability of a readme.

API documentation needs differ greatly from one project to the next, but the expected metadata will always be the same: "Who made this?", "What license?", "Where can I find more info?"

I still remember when I started programming and saw things like b.plugin([plugin], opts) in titles. It was completely confusing and made the project less approachable, because the syntax requires an understanding of jsdoc or programming at least, to understand why the "plugin is in an array". It's not, but if you're new to programming it looks like it. If the goal of documentation is to help users understand how to use the library, then it behooves the library to write documentation that a new programmer can understand.

After spending 15 years of my career in SEO/SEM, I tend to make decisions based on actual numbers and statistics, balanced with my own perspectives and experience. For documentation I lean towards things that are preferred by search engines, since no one will be reading your docs anyway if they don't know your project exists (statistically speaking, across all of my projects google is responsible for the majority of project visits. along the lines of 60% of total traffic on average). If you can also make your documentation approachable to new developers, or non-developers, then all the better.

just my 2c

[zcei]

I still remember when I started programming and saw things like b.plugin([plugin], opts) in titles. It was completely confusing and made the project less approachable, because the syntax requires an understanding of jsdoc or programming at least, to understand why the "plugin is in an array". It's not, but if you're new to programming it looks like it.

With this argumentation, we can stop building an API section right away. There are always people not immediately grasping the intention of a syntax.
As no other types are defined in b.plugin([plugin], opts), you shouldn't assume, that it's meant to reflect an array.

I tend to make decisions based on actual numbers and statistics

That's definitely a wise approach and I recommend keeping this up 😉
Plus, I agree that search engines should be able to easily parse your docs.

But for me, that's up to the documentation tools you're using. You have a huge project? Go on and parse your docs out of JSDoc annotations. Small project? Keep everything in the readme (if you want to, you can still generate it from source code annotations)

The API section should outline how to use the code. No one prevents you from having e.g. links to classes in it, which are described in the verbose part of your docs.

For me it's a timely matter. You will always first look at a projects readme, before jumping into the docs.
At this point in time you can already decide whether the API looks appealing to you, before you actually know which tons of configuration options the third sub-class of an parameter has. (exaggeration)

Plus there may be cases when an package has no parsed/hosted docs available. You would then need to get the source code and generate docs on your own.
Your readme would still have the outline

[yoshuawuyts]

I unsubscribed from this issue but someone mentioned me, so here I am.

I feel there's a silly amount of bikeshed going on in this project. Would-be syntaxes are discussed without a single line of code existing. Six months ago all the proposals, ideas and discussions fell dead and nothing usable was created.

So what I propose everyone with an interest in some sort of standard readme does, is to go out, and make things. Concensus will never be reached, but at least there'll be tangible things out there that can be used and improved upon. Cheers.

slowly retreats back to slumber

[zcei]

Six months ago all the proposals, ideas and discussions fell dead and nothing usable was created.

That was mainly my fault and in no way related to the useful-ness of a standard readme.
As soon as I got all struggles with my new job sorted out and got time to return to the project, a lot of people were immediately back on track.
So for me it feels like, there is still an urge to create something.

everyone with an interest in some sort of standard readme does, [...] go out, and make things

won't make it any better. That's what we're doing for the last few years. Where is the standard? It seems the only thing everybody can agree on, is that a readme is needed..

And absolute consensus is definitely unreachable, but I don't see why this should be an argument to not even try gaining an overview of preferences..
It feels like you're just jumping in to rant against anyone who's thinking before jumping into coding.

rtype might not have a code base, that allows you to validate everything, but Markdown as itself for me is some kind of code, and their proposal and arguments seems valid to me.
It's a more functional approach of writing your function signatures - but would you claim, every functional language has a would-be syntax? (some have quite a similar syntax)

[jonschlinkert]

@yoshuawuyts from your response it sounds like maybe I came across in a way I didn't intend. If so please accept my apologies. I like this idea, and I was hoping to join the convo and thought it might be fun to help out. good luck!

[wooorm]

Don't worry, Jon, Yoshua's comment wasn't directed at you, rather, at the fact that 95% of the talk surrounding this project is about API section design (without any solutions).

To a certain extend, I agree with Yoshua and I suggest taking API section syntax off the table. At least for now. And, instead, directing our work towards the other sections.