Doc Optimization

[patrickarlt]

This PR proposes some of the changes I suggested in #137 (comment).

1. On pages for functions like createItem
2. Where there is a function param called requestOptions
3. Print a table under "Options" with all the properties of the type of requestOptions.

Then to add some more value

1. where the return type is a known declaration (i.e. something we have defined) in the library somewhere OR
2. A promise that resolves to 1
3. Print a table under "Returns" with all the properties of the type of the object.

This makes pages like createItem MUCH more useful since you can now reference all the options AND the return values on 1 page mostly resolving @dbouwman's issues in #137 (comment).

[dbouwman]

The output looks great @patrickarlt! The build is failing in CI though...

[jgravois]

the build is failing because the postinstall script has been removed from the package.json.

if we don't want to bootstrap automatically on npm install anymore another option would be to add the command to the travis.yml as a before_script

[codecov]

Codecov Report

Merging #469 into master will not change coverage.
The diff coverage is n/a.

@@          Coverage Diff          @@
##           master   #469   +/-   ##
=====================================
  Coverage     100%   100%           
=====================================
  Files          94     94           
  Lines        1209   1209           
  Branches      219    219           
=====================================
  Hits         1209   1209

Impacted Files	Coverage Δ
packages/arcgis-rest-geocoder/src/geocode.ts	100% <ø> (ø)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update ba893b7...d7a2772. Read the comment docs.

[patrickarlt]

Fixed the build. I was having some issues related to npm install and lerna bootstrap

[jgravois]

i'm pumped about this pull request @patrickarlt!

when you DRYed up the code in 7f58e72 you must have busted something, because the table documenting what is returned is no longer populated.

[patrickarlt]

@jgravois whoops should be fixed now.

[COV-GIS]

This is great @patrickarlt! The docs will be much more user friendly.

If you have time take a look at this... https://github.com/Esri/arcgis-rest-js/blob/master/docs/src/js/nav-toggle.js#L8-L12 matches both @esri/arcgis-rest-feature-service and @esri/arcgis-rest-feature-service-admin. So clicking @esri/arcgis-rest-feature-service opens both sub menus. I couldn't see a simple and elegant solution. Mildly annoying more than anything.

[noahmulfinger]

Looks great! Two notes:

• I didn't do a full check of all pages, but I found a few pages that didn't show the Options table.

  • /arcgis-rest-js/api/users/getUserNotifications/
  • /arcgis-rest-js/api/users/getUser/
  • /arcgis-rest-js/api/users/getUserInvitations/
  • /arcgis-rest-js/api/feature-service/getLayer/
  • /arcgis-rest-js/api/groups/getGroup/

• This is not blocking, but UI-wise its not super clear to me that the Options table refers to properties of the requestOptions param. Maybe just titling it "requestOptions Parameters" or indenting the Options table slightly would work. In any case, some sort of connection would be helpful.

[patrickarlt]

@noahmulfinger I added support for when we need to handle things by named reference not just by ID. This resolves almost everything in your list.

However for arcgis-rest-js/api/users/getUser/ it accepts a union which is a BUNCH more work that I would rather delay. I might be able to get to it by dev summit, I might not.

As for the header this now says "Available requestOptions"

feedback addressed.

[jgravois]

thank you @patrickarlt for the massive DX improvement and @noahmulfinger for the shrewd feedback!