Node-restify: Missing Documentation

[stevehipwell]

The current v5 documentation is an improvement on what we had before but it still isn't good enough for me to write the new TypeScript definitions from.

Documentation issues:

• Change server.version to be server.versions

Missing documentation:

• API documentation for Router/Route
• Update server options values to reflect all options
  
  
  
  • Undocumented options are referenced in the comment for httpsServerOptions
  
  
• Request and Response properties documented like server properties

[essuraj]

Also breaking changes if any ... nevermnif found here .. but would love it on the site

[retrohacker]

@essuraj absolutely. This probably belongs under the guides sidebar in docs. Submitting a PR now :smile:

@stevehipwell thank you for helping us find short-comings in the documentation :heart: we shipped knowing there were gaps but we have far more work on the project than maintainers can tackle at the moment, though our team is growing :tada:.

Our hope in shipping the code base was that the community would help us identify and fill in the gaps. Before the 5.x release, we didn't have a great process for accepting documentation contributions from the community. I prioritized the new website so that we had a solid process to accept documentation contributions :smile: the docs in this repo (under ./docs) are used to populate the Docs tab on the new website so a simple PR agains those will result in the website being updated.

Keeping issues and PRs on this repo flowing has taken up a majority of my time post-release. I probably won't get to a documentation deep dive for a few weeks. Between now and then, possibly one of the community members or another maintainer will have a few cycles to help out on this :heart:

[retrohacker]

@essuraj https://restify.github.io/docs/4to5/

[stevehipwell]

@retrohacker - I have tried to figure out what was part of the restify public API when updating the TypeScript typings for v5. I'm happy that I've got the correct functions but I'm less happy that I've got the public values right. To get these perfect I'm more interested in a basic list of the API surface rather than full documentation. Obviously as the documentation improves I'll be able to improve the typings intellisense.

[retrohacker]

@stevehipwell thank you for all of the time you are investing in helping the restify TypeScript community <3

Are the JSDoc type definitions enough for what you need? Each function should have them. I.E. https://github.com/restify/node-restify/blob/5.x/lib/server.js#L70-L71

[stevehipwell]

@retrohacker - That's my pleasure, I'm a big fan of restify and want to make it the first choice TypeScript REST API for node.

The JSDoc type definitions are great for the functions but I really need to know what values (e.g. server.log) are considered public. I've got values in my definition that I think are correct but I can't be 100% sure and I don't want to expose implementation details that aren't meant to be part of the public API.

[retrohacker]

I believe we have a convention of prepending _ to properties and methods that are intended to be internal. For properties that have a JSDoc definition, we also use @private.

It should be safe to assume that properties without a prepended underscore and/or the @private tag are public :smile: there may be a few cases where we are inconsistent but we can fix those with a PR moving forward :heart:

[stevehipwell]

👍

[hekike]

@stevehipwell take a look to the new JSDoc based documentation it should contain all the parameters with types:

https://github.com/restify/node-restify/tree/master/docs/_api

[stevehipwell]

Thanks @hekike

[retrohacker]

:tada: you are amazing @hekike, thank you!