nodejs / docs Goto Github PK
View Code? Open in Web Editor NEWA place for documentation. (this repository is inactive)
License: MIT License
A place for documentation. (this repository is inactive)
License: MIT License
Hello - I noticed some items on Timers are also documented on Global Objects, but not consistently.
These items are listed on both Timers and Global Objects:
clearInterval(t)/clearTimeout(t) and setInterval(cb, ms)/setTimeout(cb, ms)
But these items are listed only on Timers (missing from Global Objects?):
clearImmediate(immediateObject), setImmediate(callback[, arg][, ...]), ref()/unref()
This is a tracking issue for a new doctool using remark. The goals are:
This issue will contain all known breakages and necessary plugins (both existing and net new), broken into "required" and "nice to have":
@include
syntax (remark-include
by @Qard)Makefile
{Type}
parsing (for parity with this PR)Makefile
testsI have the following scenario:
"dependencies": {
"http-proxy": "^1.12.0"
},
"devDependencies": {
"gulp": "^3.9.0",
"gulp-zip": "^3.0.2"
}
I have to bundle my application code, as well as the http-proxy module, into a zip file in order to upload to my server (eg. aws lambda, or my server doesn't have internet access).
I don't want to zip up all 140 directories inside of node_modules when creating my deployment package. Instead, I want to only zip up my application code, http-proxy, and http-proxy's dependencies (eventemitter3, requires-port).
Is there a programmatic way to query npm in order to return an array of folders based on an array of modules?
In this example:
getFoldersFor(['http-proxy'])
-- or something --
where it would return:
['http-proxy', 'eventemitter3', 'requires-port']
so I could then only zip up those 3 folders into my application's deployment package (zip).
bundledDependencies looks like it is only for npm publishing, so that probably won't work directly.
With npm2, this was easy, as everything was nested. With npm3, there's no documented way of doing this.
Thanks!
Crosslinking this issue here: nodejs/Intl#9
cc @nodejs/documentation
I'm trying to figure out a good way to add something to our release process to auto-generate the docs for deps/v8
and dump them somewhere online. The intent is to have a folder tree something like /docs/internals/v8/{node_version}
where you can view V8 docs for the relevant node/io.js version.
Challenges:
Perhaps there could be a node service with doxygen and git already installed that watches github releases, checks out the matching commit, runs doxygen, and dumps the resulting files in S3 or something like that? Anyone have any feedback on this idea?
cc: @chrisdickinson
Previously handled in nodejs/nodejs.org#211. Echoing here.
Open questions were:
Feedback: some localization groups have started the translation of API docs (iosj-ru, iojs-es). The documentation wasn't migrated over the documentation to the website group. Tooling missing at the moment.
We should document the process of benchmarking in node so we have a resource to point contributors at.
This could include such topics as
I recently wrote a short tutorial on how to use the built in profiling capability in node to optimize app performance. I was wondering if the docs wg were interested in including this or something similar with any other guides or tutorials you have.
Here is the tutorial: http://pastebin.com/5v3TiNY8
Leave your name here if you're interested in contributing to the Docs WG.
This is a continuation of #79, I've noted that there're a few styles not following (that I know of) explicit conventions.
The ones I could came up with:
'true'
to reference a boolean value once but mostly uses just true
.I'm missing any?
I've just had the second person using normal ticks instead of backticks and not understanding why examples aren't working. Template strings are a relatively new feature and people are getting confused by the examples:
I think our examples should somehow emphasize that these are backticks (not really sure how), or we should avoid backticks except when discussed in the examples, or we can have a small FAQ page for that.
As it is, users get confused. Opinions?
I can write a PR once a decision is made.
This issue will be used to track progress on documenting the internal intialization process as listed in the Roadmap (which currently can be found at #70)
I believe this documentation should include:
Hi – I'm taking this task for myself.
I'm going to investigate documentation tooling for this repository.
Goals:
It's pretty likely these'll live as npm
scripts (npm test
, npm start
, npm run export
, etc.)
Hey folks! If you're interested in joining the Docs WG — or in helping out with the Node docs in general, leave your name here. We'll onboard folks on a regular basis. Thanks!
(Previously: #2)
I'm raising my ✋ to write the overview article which was called out in this quarter's roadmap #70 - I believe my understanding is good enough from previous writing I've done on the topic.
A PR on the event loop is currently open at nodejs/node#4936 and because of the relationship between the event loop and blocking, my plan is to start on the "Blocking vs. non-blocking" overview but ultimately make sure the event loop PR is merged first and be sensitive to unnecessary overlap.
@chrisdickinson @techjeffharris sound ok to you?
A common pattern probably in any node
programming style, is to pass options. Contrary to, say golang
, it's rather common to pass some let options = {}
. Especially on OOP js
I assume this is heavily used for class instance configurations.
However, using plain js
can sort of make a quick end to this approach, when used with nested objects.
Even though this might be a small guide and pattern this could lead to better style of the community if we'd advise for a solution. Object.assign(defaultObj, [...objs])
could now be nicely used for this. See examples (old and new below):
'use strict'
function oldApi (options) {
let opts = options || {}
opts.name = options.name || 'the default name'
opts.test.count = options.test.count || 1
return opts
}
let testOptions_1 = {
name: 'better name',
test: {
count: 2
}
}
console.log(oldApi(testOptions_1));
// let testOptions_fail = {
// name: 'better name'
// }
// console.log(oldApi(testOptions_fail)); this will fail ->
// TypeError: Cannot read property 'count' of undefined
function api (options) {
const someDefault = {
name: 'the default name',
test: {
count: 1
}
}
let opts = Object.assign(someDefault, options)
return opts
}
let testOptions_2 = {
name: 'better name',
test: {
count: 2
}
}
console.log(api(testOptions_2));
// let testOptions_success = {
// name: 'better name'
// }
// console.log(api(testOptions_success)); // this will not fail
We are way overdue for another meeting. 4.x has been out for awhile now, and @nodejs/website has the keys to nodejs.org now. We need to coordinate with the Website WG to get what we've got onto the website and do something about the collaboration-unfriendly state the repo is currently in.
I've put together a doodle to find a time next week: http://doodle.com/poll/8wwpw97f62gpawrx
The agenda doc is here, please suggest more stuff to discuss:
https://docs.google.com/document/d/1TdP8dKDy24nM3Scv9I-NN-RsFbuveX8Foys01SCh-bw/edit?usp=sharing
@nodejs/documentation @nodejs/website
Time for another meeting.
This meeting is scheduled for 2016-01-20 @ 10:00AM PST, and will be a public-viewable Google Hangout on the Air.
If you participated in the Doodle poll, then your Github username should be in this list, and you should have received an invite. If not, and you want to participate, please email me ([email protected]).
Minutes will be recorded in this Google Doc and then committed back to this repo after the meeting. Please let me know if you want write access to the doc.
There are several outstanding issues in joyent/node requesting better documentation
of setTimeout, setImmediate, and process.nextTick. Opening this to consolidate the
reports and track status. Will add links to the original issues here, but closing those
original issues.
Hey,
After the last docs WG meeting we figured out we need a better way to measure how understandable the docs are and what newcomers find confusing.
I'd like to toss around ideas for how we can measure how understandable the docs are.
When I use http.request, I can get an instance of the http.ClientRequest class. Also I need handle error event like this:
req.on('error', function(e){
console.log('Error: ' + e.message);
});
However, no Event: error in http.ClientRequest.
The same to Event: data in http.IncomingMessage.
In my experience, Node.js will report many errors like EACCESS, EPIPE, etc. No where are these errors documented (what they mean and when they occur). This seems like a big issue.
Why it's a pretty significant issue is because errors is one of the most common thing developers must handle, and a vague error is the worst kind of error. I believe Node.js can do better; I think every error from Node.js core framework should be documented and explained.
PS: This is a duplication of the original issue for nodejs.org nodejs/nodejs.org#162 (comment)
At the Node.js Collaborator Summit, it was decided that a Documenation Working Group meeting needs to happen.
So let's do it.
Aug 18th, 2015, at 20:00 UTC. (See this in your local time zone.)
Participant link: https://plus.google.com/hangouts/_/hoaevent/AP36tYeG3AQAvPNE5qmWKaTc-2s7DgxyhV-MelM43peyBHJhC84DZg
Link to watch: http://www.youtube.com/watch?v=Z-nYI5Q5myM
Minutes Doc (will be in repo after meeting): https://docs.google.com/document/d/1Q1HyzOf-kjx2giZgSzg5hTY8omieux5mQRykwLHboxU/edit?usp=sharing
Email me ([email protected]) if you want edit access to the minutes doc.
Please comment here if you're interested in attending and your name's not here.
If you'd like to add further topics, please mention so in comments.
It would be handy to have a guide that introduced "how to introduce large features into Node". It should touch on the planning process, review, and bits of implementation — for example, the use of feature flags to gate access.
There's been a bunch of discussion with regards to getting ratified on the Node tracker.
The current proposal is:
doc/
, tools/docs
; and shares responsibility for doc/api
with the core team.While I've been in contact with a few of us, I'd like to make sure we're OK with this plan going forward.
/cc @nodejs/documentation
I would like to attempt a first version of the guidetopic to asynchronous programming.
The intended audience is javascript programmers new to node.js.
This doc would probably live at src/topics/async.md
.
I'm thinking of the following rough outline:
It would really help if the API documentation had some kind of consistent markup that described at what node version and API was introduced and or changed in a backwards incompatible way.
For example io.js newSession docs doesn't at all mention that the callback argument is new since 0.10.
Would this be a good place to report this?
The thing that is needed IMO is:
(Not sold on the title. Ideas pls!)
I have a lot of time on planes coming up in the next few weeks so I thought I'd seize the opportunity. I'd like to put together a in-depth guide on how HTTP requests are handled. This could be a replacement for, or something to go alongside, a "Your First Webserver" guide.
I'd start it out with a very basic web server (possibly all at once, possibly bit by bit as concepts are introduced, haven't decided yet), and iterate through basically every line explaining what is going on. I want to break down the order in which things happen, which events get fired when, etc., which is often a source of confusion. I'd be gearing this toward people who are brand new to node, maybe have done a "Your First Webserver" tutorial or something (or maybe not) and want to get a better understanding of what's actually happening.
How's that sound?
The following is a transcription of the topics discussed at NodeConf. This board will serve as the backlog proposed documentation improvements. The list is not prioritized. As the efforts are prioritized, they will be converted into Github issues which can then be assigned to individuals and implemented.
https://trello.com/b/OK2TBRw1/node-js-documentation-brainstorm
Note: The board can be viewed by anyone but I will have to individually add people in order to grant "Edit" permissions. If you would like to add or edit the board, please leave your email below or email me at [email protected] and I will add you as a collaborator immediately.
This issue will be used to track the status of created a guide to document the internal release process as outlined in the Roadmap (currently found at #70)
Currently the doc lives in docs/releases.md
One of the action items from Nodeconf was to put together a set of values for both our docs and our team so that we've got a good basis for making decisions about the docs. I'm going to take a stab at writing this over the next day or two.
My goal will be to cover strategic values, tactical values, and mechanical values – so that any doc team member can easily use these values when determining what to start writing, how to write it, how to edit it, and what to look for when editing other's work. I will submit the style guide piecemeal to this repo as a series of PRs so that we can discuss these values.
A brief definition of terms: strategic values will influence our long-term goals for these docs. They should help us decide how to move the project forward and set priorities.. Tactical values influence the actual writing of the docs – what to write and how to approach writing it. Mechanical values are the most like a traditional style guide – how to format the documentation source, grammar rules, etc.
If folks have input ahead of the PRs, please comment here! I'll be associating all of the PRs with this issue so you'll see 'em as they pop up.
I have tagged issues from the old iojs/website repo, now located at nodejs/iojs.org, with docs and invalid to indicate that they should be handled by the Docs WG, and removed them from the new.nodejs.org agenda.
These issues are still important, and need to be addressed. They just aren't in the perfect place to do so - thus, this issue has been created.
List: node/iojs.org - issues tagged with "docs"
These issues are something that I think can be taken care of by the Docs WG. Feel free to pull these into an issue or PR in this repo - if you do, though, make sure you link the issue in nodejs/iojs.org you're working from.
I just updated the members in the readme.md (didn't know that I have push rights here) according to @chrisdickinson 's lists
This meeting is scheduled for 2016-02-03 @ 10:00AM PST, and will be a public-viewable Google Hangout on the Air.
I will place the Google Hangouts link for participants in the Docs WG Slack, and link the public URL in this issue.
Minutes will be recorded in a Slack Document that will be shared in the channel, then committed back to this repo after the meeting.
We will be revisiting the time of subsequent meetings to make sure everyone invited can attend.
I would like to take the plunge and write a tutorial on installing Node as I think that this simply should be the first doc we have. What do you think?
That said I think that it pretty much resembles https://nodejs.org/download/ - how should it relate to it? Will it replace it or should we link to it for the latest versions?
Are there any topics you'd like to be covered?
This will track progress on a Documentation Overview of Timers in Node, as suggested in the Docs WG Roadmap for Q1 2016 (#70). Since an understanding of the Event Loop is pretty essential to giving context for timers, I'll be using nodejs/node#4936 as a branching off point to explain how timers work and best usages of the different API functions.
Here are some ideas I have for topics to cover:
Differences between intervalObject and timeoutObject and how they wrap Timer objects
Timer internals, like the linked list structure
... more to add
Any suggestions for topics are appreciated!
Heya,
It seems prudent for this WG to take responsibility for the documentation on new.nodejs.org
.
Right now this section is called "Resources" but that is not a great name and should probably be changed to something better which is also something I think we should leave to this WG to decide :)
You can name it something else by editing this file https://github.com/nodejs/new.nodejs.org/blob/master/locale/en/site.json
Creating the page is pretty simple, I would use the "About" page as a guide for how the template and build system works.
Keep in mind that all content is templatized for localizers.
Let me know if you have any questions.
I heard mention in the hardware wg that the docs team may be looking for someone to write a tutorial about running nodejs on embedded systems. is this accurate? I was looking to help out, but need more information.
thanks
In #4765 an individual asked why a dependency was not being included as a submodule
https://github.com/nodejs/node/pull/4765/files#r50186199
Afaik we do not have the management strategy for dependencies documented anywhere.
Here is my response.
Currently for dependencies such as v8, libuv, or npm we take version updates as a single commit updating the state of the current directory, generally from a collaborator of the project we are downstream from. In between large updates we will sometimes backport changes as individual patch's.
Where should something like this live?
How specific should it be?
Should it be documented on a per vendor basis?
Should this be a standard that vendors adhere to?
edit: the last two points may be a bit out of scope for this issue, but I am concerned about how specific this should be if it is considered authoratative
There's an issue (nodejs/node#2165) with HFS+ where unicode paths returned by the file system are not necessarily the same as the ones that were written because HFS+ forces certain code points to be in NFD form apparently. The consensus looks to be to avoid unicode normalization in node and instead delegate the normalization task to the user.
I could litter all related methods in fs
and process
with a note that strings aren't necessary comparable depending on file system, but I think a better approach would be a section where we could advice on pitfalls like this.
There seems to be a disconnect between the website and the docs wg. I feel like it'd help to merge our content files into https://github.com/nodejs/new.nodejs.org and do all future documenting there, using this repo purely for communication and documenting the process of contributing docs. Does anyone have any strong opinions here?
I'd be happy to do the migration, if we want to go forward with it. It'd mainly just be a matter of dumping files into https://github.com/nodejs/new.nodejs.org/tree/master/locale/en/docs and adding some yaml headers to things.
@nodejs/documentation @nodejs/website
This came up in the roadmap with #70 and I volunteered to get some content put together. I've done some local presentations on it for the JS folks in my town. I really enjoyed a talk by Philip Roberts @ JSConf EU 2014 something like that could be made more Node-centric and distilled into some GIFs for a presentation to help illustrate it.
cc/ @chrisdickinson
Even though it might not sound too sexy to contribute / express opinion to / about docs, I want to promote this thing, say at reddit
. Catch phrase: "there is a doc WG now, please contribute / tell your opinion. We want to be the best docs out there". Does that seem valid to you?
As part of our charter, this WG is required to review documentation coming through PRs in nodejs/node. However, we're to avoid blocking PRs from landing solely based on documentation concerns.
As a result, I propose we start a review of docs that have landed on the master
branch of Node over the course of the past week. Our goal will be to clarify, correct, and edit recently landed API docs. This should prevent the Docs WG from blocking Core contributors from landing work, while ensuring a high quality of documentation for releases. Docs to be reviewed will be reported in the Docs WG Slack.
If your interests lie in spelling, grammar, or editing, this is a task that could benefit from your skills. Please comment on this issue if you're interested in helping out with this.
This doesn't appear to be explained in the HTTP API docs. It should be there for clarity. For the moment, it seems that this comment in the source seems to be the only place it's mentioned.
I came to this repo hoping to help out with docs-writing, read the CONTRIBUTING.md, and then started poking around the repo looking for examples/some idea of the state of things.
All I found were mystifying nested folders and some old discussion on the issues. What now?
Let's put a readme in place so nobody gets lost. It can be very basic, but needs to include such information as:
Onward and upward!
I've created a Docs WG Slack and invited the current members. If we decide we don't want to use this, it's totally fine — but gitter seems like it's been a ghost town, and it'd be good to have a space for continuous / real-time-ish discussion.
If you haven't received an invite, please email me at chris at neversaw dot us
.
Hi all —
I've noticed that it can be overwhelming to look at the state of the docs and try to pick a single thing out to work on. There are a ton of things that need improvement, and everyone sees different deficiencies in the docs. Further complicating matters, the docs are a relatively tight space to work within — it's really easy to end up stepping on other folks' toes when making larger changes.
With that in mind, I'd like to run a quick exercise. In this issue, I'd like you to list as many different features, tools, or docs that you think need work. At this point this is unranked listing — no +1's or votes at this point, please! Feel free to repeat items others have said, though. Examples might be:
I will close this issue at the end of the week and put forward a roadmap for discussion.
/cc @nodejs/documentation
I was writing up a piece, that should give new comers and example work through of how node is built and how you can traverse the stacks. It is doing this by introducing a new feature hello_world
from scratch (I continued working of extending path
though) with having v8
, libuv
, js
code and hooking it into the build system.
It was missing some parts at the libuv
-to-v8
level and explanations how reading in js
strings with vm
works. With some senior support I could actually be able to complete this.
Does that sound interesting in terms of the roadmap? #70. Also might touch the current issue of nodejs/node#4931
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.