Update docs to Frameworks API
ClosedPublic

Authored by jriddell on Mar 10 2017, 1:54 PM.

Details

Summary

Update API docs

Test Plan

Read them

Diff Detail

Repository
R283 KAuth
Branch
docs
Lint
No Linters Available
Unit
No Unit Test Coverage
jriddell created this revision.Mar 10 2017, 1:54 PM
Restricted Application added a project: Frameworks. · View Herald TranscriptMar 10 2017, 1:54 PM
Restricted Application added a subscriber: Frameworks. · View Herald Transcript
leinir requested changes to this revision.Mar 10 2017, 2:13 PM

Thinking this is... well under way, with a couple of details :)

src/kauthactionreply.h
338 ↗(On Diff #12366)

Thinking it would be kind of good to translate this into something more useful for the Action::AuthStatus enum documentation... Just removing it entirely seems to me to get rid of the verbose "don't use this for your own errors, this is for authentication only, you should look over here" thing which is inherent in the current text... Perhaps simply adding @see ExecuteJob::newData to that enum's documentation might do the trick?

src/kauthexecutejob.h
85–93

Returned isn't semantically right, here, though the term "helper" is a bit ambiguous... What is meant by "sent by the helper" is more to the point "send by the helper using HelperSupport::progressStep(QVariant)"... which is somewhat clunky, but explains more properly what is going on here. Return would suggest that it is only done at the end, whereas this can, specifically, be done multiple times (basically, every time progressStep(QVariant) is called). So... perhaps changing this to be something like

/**
 * Use this to get the data set by HelperSupport::progressStep(QVariant)
 * This function is particularly useful once the
 * job has completed. During execution, simply
 * read the data in the newData signal.
 * @see ExecuteJob::newData
 * returns the data sent by the helper
 */
This revision now requires changes to proceed.Mar 10 2017, 2:13 PM
jriddell edited edge metadata.
jriddell marked an inline comment as done.
  • better description for kauthexecutejob data
  • mention statusChanged
jriddell marked an inline comment as done.Mar 10 2017, 5:48 PM

added some info to kauthexecutejob.h about AuthStatus

data() does get the data returned by the action (not direct return I guess) as well as set during the action, updated.

src/kauthexecutejob.h
85–93

it can also be set by the return of the auth action so I mentioned both

leinir accepted this revision.Mar 13 2017, 8:42 AM

That looks about right to me! :)

This revision is now accepted and ready to land.Mar 13 2017, 8:42 AM
This revision was automatically updated to reflect the committed changes.