Closed yoshuawuyts closed 8 years ago
I kinda like the blade API style
Looks like this:
blade.compile(string, [options,] cb)
Compiles a Blade template from a string.
options.sync
is setstring
- a string of Bladeoptions
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
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.
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.
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.
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.
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.
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?
I like the idea of using a jsig
subset, basically it'd look like this:
Example
sectionCompiles a Blade template from a string.
cb: (Error, compiledHTML:String) => void
options: Object
filename: String
required when using includes
or the cache
optioncache: Boolean
defaults to false
Example:
blade.compile('h1 foo\n\t| sum text', function(err, html) {
console.log(err || html);
});
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
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 :)
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.
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
Something that matches with dox would be nice
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|
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 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)
Yields:
Thus, escaping of [
may or may not be needed. The alternative is code ticks:
# `b.plugin([plugin], opts)`
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?)
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! :beers:
@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.
@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! :beers:
Regarding your last two points (and please don’t edit comments without stating what you changed) of https://github.com/zcei/standard-readme/issues/3#issuecomment-172595075:
browserify
, virtual-dom
, from2
, safe-buffer
, webtorrent
, multicast-dns
, concat-stream
.And regarding your last https://github.com/zcei/standard-readme/issues/3#issuecomment-172604467, sure, but this project is called standard-readme and not sindre-readme or tj-readme :wink:
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 :wink:
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!
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.
Okay, I’ll outline some actionable things soon in a separate issue.
@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.
@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.
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
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 :wink: 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
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
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)
@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!
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.
originally posted in https://github.com/feross/standard/issues/141#issuecomment-107029135
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
withopts
. Plugins can be a string module name or a function the same as transforms.plugin(b, opts)
is called with the browserify instanceb
.For more information, consult the plugins section below.
virtual-dom
Patch operations
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, thepatch
function will update the DOM. After applying the patches to the DOM, the DOM should look like the newVTree
.from2
stream = from2.obj([opts], read)
Shorthand for
from2({ objectMode: true }, read)
.