Feature request #12292
Complete API Documentation
| Status: | Open | ||
|---|---|---|---|
| Priority: | Normal | ||
| Assignee: | - | ||
| Category: | Documentation and Help | ||
| Pull Request or Patch supplied: | No | Resolution: | |
| Easy fix?: | No | Copied to github as #: | 20470 |
Description
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).
History
#1
Updated by Giovanni Manghi over 9 years ago
- Category set to Documentation and Help
#2
Updated by Nyall Dawson over 9 years ago
They should already be sorted - can you post an example of an unsorted member?
#3
Updated by William Wilson over 9 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.
Example: http://qgis.org/api/2.8/classQgsMapCanvasLayer.html
#4
Updated by Nyall Dawson over 9 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...!
#5
Updated by William Wilson over 9 years ago
That is very good news.
I will have to investigate moving to v2.8.* once all the major issues/bugs have been dealt with from 2.8.0
#6
Updated by Giovanni Manghi over 7 years ago
- Easy fix? set to No
#7
Updated by Harrissou Santanna about 7 years ago
- Description updated (diff)
Now that there's an (ongoing) automated process to document the API, is this still valid?
#8
Updated by William Wilson about 7 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:
https://qgis.org/api/2.18/classQgsMapCanvasLayer.html
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)