Feature request #12292
Complete API Documentation
|Category:||Documentation and Help|
|Pull Request or Patch supplied:||No||Resolution:|
|Easy fix?:||No||Copied to github as #:||20470|
The API is quite incomplete, missing descriptions for countless public functions. Additionally many of the functions that are documented provide little information about the operation they perform. Ex.
QString QGsVectorLayer::metadata() reads 'Obtain Metadata for this layer.'
Since there is no 'setMetadata' function it seems crucial to provide some expanded description for this function at minimum the expected format of the returned QString.
As an extra option it would greatly improve the usefulness of the API documentation if the functions could be sorted alphabetically. Either entirely alphabetically or in standard form of Constructor(s), Desctructor, public functions, static public functions (ex. Qt's API).
#3 Updated by William Wilson almost 5 years ago
I have been dealing with this issue for a while and only got around to posting it now (from version 2.6.*).
In 2.8 you are correct they are indeed sorted. I suppose none of these issues will be corrected on older API versions.
An example, simply for correctness: http://qgis.org/api/2.6/classQgsVectorDataProvider.html
*While the issue appears to be much less severe in 2.8, the documentation isn't complete/could use further explanations.
#4 Updated by Nyall Dawson almost 5 years ago
It's definitely a valid issue. FYI, in 2.8 and above we have a unit test to ensure that the documentation coverage doesn't drop. This doesn't fix existing methods which are missing docs, but it does prevent new methods/classes being added without documentation. Of course, it can't test for quality of the documentation...!
#8 Updated by William Wilson about 2 years ago
The coverage is getting better, but I suppose it depends on the definition of "valid". Just as my example above shows, in the new 2.18 version, most if not all functions have no description:
Reviewing the code to determine what each function does isn't really a realistic option for someone trying to use the API.
*The inherited/protected/etc. links also do not appear to do anything despite being links and having onclick/JS assigned. (Tested with FF: Linux and Windows)