search

sailfishos / sailfish-secrets

BSD 3-Clause "New" or "Revised" License
24 stars 15 forks source link

Rendering issue in the documentation #116

Open dcaliste opened 6 years ago

dcaliste commented 6 years ago

I'm more and more using the generated doc to find function names and enumeration values, or check for return codes. It's very nice and useful. But…

Enumerations are not detailed in the documentation. For instance, looking at the ErrorCode from Secret::Result, the short listing at the beginning of the result page lists something like: enum ErrorCode { NoError, UnknownError, SerializationError, PermissionsError, ..., OtherError }, which is fine for a short(ened) list, but when going to the full details, by clicking on the ErrorCode link, there is just the enum name, something like enum Result::ErrorCode. All the values and their meanings are missing.

It's true for every enums. It makes the documentation less useful than it could be. Is it because some markups in the sources are missing or a flag to turn on when generating the doc?

Venemo commented 6 years ago

I don't think this is a rendering issue. If you look at the definition of these enums, eg. https://github.com/sailfishos/sailfish-secrets/blob/master/lib/Secrets/result.h#L37 - you can see there are no documentation comments in there. I also didn't find these in the cpp.

I would say that most of them are pretty self-explanatory, but I realize this is a very poor excuse for not providing documentation for them.

We simply need to document these properly.

dcaliste commented 6 years ago

I understand that names are clearly self explanatory, the problem is that names are not outputted in the HTML files of the documentation… which make the HTML pretty useless when looking for enum values. If at least the documentation would list the names without any associated sentence for documentation would be fine already. I don't know QtDoc enough to say if it's a bug, or expected that enum are listed only when documented.

Venemo commented 6 years ago

I belive QtDoc would need them all to be documented to render them in the doc. Though I don't have much experience with QtDoc, so just guessing here.

Venemo commented 6 years ago

Once I'm finished with my current task I can look into documenting the enums.

dcaliste commented 6 years ago

Thank you, I can help if you want.