Merge pull request #600 from moekm/develop

Improved documentation README.md

readme.md

@@ -19,17 +19,60 @@ JavaScript library to detect Browser, Engine, OS, CPU, and Device type/model fro
 * Source    : https://github.com/faisalman/ua-parser-js
 
 # Documentation
+### UAParser([user-agent][,extensions])
+typeof `user-agent` "string".
+
+typeof `extensions` "array".
+
+In The Browser environment you dont need to pass the user-agent string to the function, you can just call the funtion and it should automatically get the string from the `window.navigator.userAgent`, but that is not the case in nodejs. The user-agent string must be passed in nodejs for the function to work.
+Usually you can find the user agent in:
+`request.headers["user-agent"]`.
 
-## Constructor
 
+## Constructor
+When you call `UAParser` with the `new` keyword `UAParser` will return a new instance with an empty result object, you have to call one of the available methods to get the information from the user-agent string.
+Like so:
 * `new UAParser([uastring][,extensions])`
-    * returns new instance
+```js
+let parser = new UAParser("user-agent"); // you need to pass the user-agent for nodejs
+console.log(parser); // {}
+let parserResults = parser.getResults();
+console.log(parserResults);
+/** {
+  "ua": "",
+  "browser": {},
+  "engine": {},
+  "os": {},
+  "device": {},
+  "cpu": {}
+} */
+```
 
+When you call UAParser without the `new` keyword, it will automatically call `getResults()` function and return the parsed results.
 * `UAParser([uastring][,extensions])`
     * returns result object `{ ua: '', browser: {}, cpu: {}, device: {}, engine: {}, os: {} }`
 
 ## Methods
 
+#### Methods table
+The methods are self explanatory, here's a small overview on all the available methods:
+*  `getResult()` - returns all function object calls, user-agent string, browser info, cpu, device, engine, os:
+`{ ua: '', browser: {}, cpu: {}, device: {}, engine: {}, os: {} }`.
+
+ *  `getBrowser()`      - returns the browser name and version.
+ *  `getDevice()`       - returns the device model, type, vendor.
+ *  `getEngine()`       - returns the current browser engine name and version.
+ *  `getOS()`           - returns the running operating system name and version.
+ *  `getCPU()`          - returns CPU architectural design name.
+ *  `getUA()`           - returns the user-agent string.
+ *  `setUA(user-agent)` - set a custom user-agent to be parsed.
+
+
+---
+
+* `getResult()`
+    * returns `{ ua: '', browser: {}, cpu: {}, device: {}, engine: {}, os: {} }`
+
 * `getBrowser()`
     * returns `{ name: '', version: '' }`
 
@@ -39,7 +82,7 @@ JavaScript library to detect Browser, Engine, OS, CPU, and Device type/model fro
 BIDUBrowser, Baidu, Basilisk, Blazer, Bolt, Brave, Bowser, Camino, Chimera,
 Chrome Headless, Chrome WebView, Chrome, Chromium, Comodo Dragon, Dillo,
 Dolphin, Doris, DuckDuckGo, Edge, Electron, Epiphany, Facebook, Falkon, Fennec, 
-Firebird, Firefox [Reality], Flock, Flow, GSA, GoBrowser, Huawei Browser, 
+Firebird, Firefox [Focus/Reality], Flock, Flow, GSA, GoBrowser, Huawei Browser, 
 ICE Browser, IE, IEMobile, IceApe, IceCat, IceDragon, Iceweasel, Instagram, 
 Iridium, Iron, Jasmine, K-Meleon, Kindle, Klar, Konqueror, LBBROWSER, Line, 
 LinkedIn, Links, Lunascape, Lynx, MIUI Browser, Maemo Browser, Maemo, Maxthon, 
@@ -61,6 +104,13 @@ Yandex, baidu, iCab, w3m, Whale Browser...
 # Possible 'device.type':
 console, mobile, tablet, smarttv, wearable, embedded
 
+##########
+# NOTE: 'desktop' is not a possible device type. 
+# UAParser only reports info directly available from the UA string, which is not the case for 'desktop' device type.
+# If you wish to detect desktop devices, you must handle the needed logic yourself.
+# You can read more about it in this issue: https://github.com/faisalman/ua-parser-js/issues/182
+##########
+
 # Possible 'device.vendor':
 Acer, Alcatel, Amazon, Apple, Archos, ASUS, AT&T, BenQ, BlackBerry, Dell,
 Essential, Fairphone, GeeksPhone, Google, HP, HTC, Huawei, Jolla, Lenovo, LG, 
@@ -107,9 +157,6 @@ VectorLinux, WebOS, Windows [Phone/Mobile], Zenwalk, ...
 68k, amd64, arm[64/hf], avr, ia[32/64], irix[64], mips[64], pa-risc, ppc, sparc[64]
 ```
 
-* `getResult()`
-    * returns `{ ua: '', browser: {}, cpu: {}, device: {}, engine: {}, os: {} }`
-
 * `getUA()`
     * returns UA string of current instance
 
@@ -193,6 +240,8 @@ VectorLinux, WebOS, Windows [Phone/Mobile], Zenwalk, ...
 
 ## Using node.js
 
+Note: Device information is not available in the NodeJS environment.
+
 ```sh
 $ npm install ua-parser-js
 ```