Refactor documentation (currently, only for NodeJS SDK)

[maxkoryukov]

Convenient and clear documentation is very important for SDK, bcz the main purpose of SDK - to make it easier to integrate service. If SDK is entangled - nobody want to use it. If SDK is clear - everybody wants to use it;)

There are jsdoc-comments for functions, methods, namespaces...

But right now the documentation is not ready for end-user (SDK user), because this doc doesn't cover all a lot of questions.

Doc-layout proposal

1. main page (readme option in jsdoc.config should point to the other file, not the main README)
   • several badges
   • introduction
   • how to read this doc
   • TOC (could be in sep. file, if the jsdoc could generate toc automatically)
   • simple example
2. Core object Route4Me
   • description
   • options
   • links to sections (Optimizations, Routes ...)
   • example (how to create)
3. Subsections (Optimizations, Routes, Addresses ... )
   • desctiption
   • methods
   • examples
4. Common objects
   • callback desc
   • all errors
   • Logger
   • Validator
   • ....

All examples should be included to jsdoc.

Overall requirements

• analytics (google analytics)
• separated TOC is required (side navigation), since there are more than 10 methods

Examples for API

Examples for API should be written separately: see #31

[Olman62]

Hi Maksim, Thank you for valuable remarks and findings. Are you talking about Node.js SDK documentation? As I know JSDoc works with javascript code. I'm agree with your opinion about source code documentation - I'll see where I can improve it myself and I'll send message about this issue to other programmers. Regards, Oleg

…

On Fri, Jan 27, 2017 at 11:44 PM, Maksim Koryukov ***@***.***> wrote: Convenient and clear documentation is very important for SDK, bcz the main purpose of SDK - to make it easier to integrate service. If SDK is entangled - nobody want to use it. If SDK is clear - everybody wants to use it;) There are jsdoc-comments for functions, methods, namespaces... But right now the documentation is not ready for end-user (SDK user), because this doc doesn't cover all a lot of questions. Doc-layout proposal 1. main page (readme option in jsdoc.config should point to the other file, not the main README) - several badges - introduction - how to read this doc - TOC (could be in sep. file, if the jsdoc could generate toc automatically) - simple example 2. Core object Route4Me - description - options - links to sections (Optimizations, Routes ...) - example (how to create) 3. Subsections (Optimizations, Routes, Addresses ... ) - desctiption - methods - examples All examples should be included to jsdoc. Examples for API Examples for API *should be written separately*. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#26>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AB2IsVO03cMUekTEGCqYfzpeQ6TTCiWfks5rWkkEgaJpZM4LwI8s> .

[maxkoryukov]

@Olman62 , currently, this issue is about JS (I will fix title).

Right now the description of issue is just a draft for doc-requirements (for me). As you could see - this ticket is attached to the milestone 1.1.0, but right now I am on version 0.1.8, and current target - 1.0.0

Currently I have just scraps of the doc, but I am going to reuse this stuff;)

---

Current docs

I have published current docs here: https://maxkoryukov.github.io/route4me-nodejs-sdk/

I am sure: if I will ask you to write some code using that documentation - you will stuck))

@Olman62, thank you for review;)