A complete ArcGIS for Python API Reference

[Thomas_Z1]

Please complete the API Reference with function's output descriptions.

Bad examples

FeatureLayer.edit_features:
https://developers.arcgis.com/python/api-reference/arcgis.features.toc.html#arcgis.features.FeatureL...

Output: dictionary

FeatureLayer.delete_features:
https://developers.arcgis.com/python/api-reference/arcgis.features.toc.html#arcgis.features.FeatureL...

Dict if future=False (default), else a concurrent.Future class.

This one-line documentation is not helpful.

I know this idea is not a feature but it would help extremely to have a more complete API reference.

By adding more information to the documentation, questions like this could be avoided: https://community.esri.com/t5/arcgis-api-for-python-questions/how-can-i-test-if-there-was-a-rollback...

[jcarlson]

You should check out the GitHub repo. I've commented there before on documentation I thought was lacking, and it was addressed promptly.

[Anonymous User]

Hi @Thomas_Z1 - thanks for the feedback. Disappointed to hear that particular documentation is not helpful, sorry it is not up to par.  As @jcarlson mentioned above - logging an issue in the arcgis-python-api repo will help us track your comments and link your comments to any changes we may make. 

We've updated the documentation hosting system with the more recent release on June 3rd. The API Reference for the 2.0.1 release has a new look in addition to updated comment.

In general, our goal for return statement documentation is to state concisely what type the returned value is. When the value is an instance of a class within the API, we hyperlink to that class documentation so you can click it and directly see the properties and methods that will exist on that return value object (depending upon the input arguments).  We know some links are missing, and we're working to make sure those hyperlinks are consistent across the API reference.  

Code snippets are how we aim to augment the return statement with examples of what specific returns will look like. We try to provide a few examples of different parameter-argument combinations so we can show variations in output based upon those arguments.

For edit_features at 2.0.1, we added code snippets to demonstrate the formatting for updates, adds, and deletes arguments. We can add the output to those code snippets for the next release to hopefully provide further clarification. What would make this more complete? The return value may be a dictionary - would an example of what that dictionary looks like help?  The return value may be an instance of the EditFeatureJob if run asynchronously, so we link to that class documentation within the return statement.  Do these changes we made between 2.0.0 and 2.0.1 make the doc more complete?

The delete_features api reference contains a code snippet of what the dictionary looks like when the future argument is False.  How could we best make the return statement doc more complete? An example where the future argument is True? 

Thank you again for the feedback. 

[KimOllivier]

I have been starting to use the Python API  and I have found it very difficult to understand the functions.

The samples are just 'showoff' examples of why you would use GIS, not how to debug the tools. I find that the arcpy documentation is much more helpful because there are example snippets on every function right in the help, not somewhere in a sample. The edit tools have 16 samples for the whole module. Most of the functions and parameters are not covered with an example anywhere. I cannot find a working example of extract_changes(). I note in the community noticeboard that there was a bug in 2020 where 'optional' parameter for the URI  were actually required. Has this changed? Let's see something working so I can backtrack to see why my environment is different.

I thought the python Open API on Github would have the source for arcgis! Some hope there, it only has a smattering of examples that give a once over lightly of each module. My initial thought was that since there was a missing function where I was porting an arcpy script I would add one myself - open source, published... (I can see a child table separately from the parent table in the GUI, so why not in the API?)