Description of problem: API documentation at /rhn/apidoc/ is not consistent with actual API implementation. Version-Release number of selected component (if applicable): Spacewalk nightly Details: * Methods channel.software.getDetails (+ Result is wrapped in list! Both label and id versions.) channel.software.listChildren kickstart.listKickstartableChannels system.listSubscribedChildChannels differs from documentation in "type" of returned values: + contentSources: array of struct { id: int, label: string, sourceUrl: string, type: string } - yumrepo_label: string - yumrepo_last_sync: dateTime.iso8601 - yumrepo_source_url: string It seems that "problem"(?) lies in (documentation of?): xmlrpc/serializer/ChannelSerializer.java * In Spacewalk 1.3 release notes (https://fedorahosted.org/spacewalk/wiki/ReleaseNotes13) is mentioned errata.publishAccordingToParents but there is no such function in documentation, nor in code. * configchannel.createOrUpdateSymlink ... documentation is hard to understand. Revision -- null vs. optional? * channel.software.getRepoSyncCronExpression It is called CronExpression, but it returns quartz expression... * system.config.createOrUpdatePath configchannel.createOrUpdatePath - Maybe it's just me, but this looks like "inconsistency" at least: Having 5-th parameter {"contents":"Kwaaaak!\n", "contents_enc64":False, "owner": "root", "group": "group", "permissions": "600", "binary": False} leads to { ..., 'contents': 'Kwaaaak!', ...}, while {"contents": "S3dhYWFhayEK", "contents_enc64": True, "owner": "root", "group": "group", "permissions": "600", "binary": False} leads to { ..., 'contents': 'Kwaaaak!\n', ...}, (first one strips trailing spaces/newlines, second-one not). * Methods system.comparePackages system.comparePackages presence of 'other_system' and 'this_system' seems dependent on 'comparsion', not mentioned in documentation so I'm not sure whether it is correct behaviour or not. (PackageMetadataSerializer?) * system.search.uuid --> Too easy to send malformed input and obtain error... in documentation is no "exception thrown on ..." Example of "bad" call: system.search.uuid(key,":")
(In reply to comment #0) > Description of problem: > > API documentation at /rhn/apidoc/ is not consistent with actual API > implementation. > > Version-Release number of selected component (if applicable): > > Spacewalk nightly > > Details: > > * Methods > channel.software.getDetails (+ Result is wrapped in list! Both label and > id versions.) > channel.software.listChildren > kickstart.listKickstartableChannels > system.listSubscribedChildChannels > differs from documentation in "type" of returned values: > + contentSources: array of > struct { id: int, label: string, sourceUrl: string, type: string } > - yumrepo_label: string > - yumrepo_last_sync: dateTime.iso8601 > - yumrepo_source_url: string > It seems that "problem"(?) lies in (documentation of?): > > xmlrpc/serializer/ChannelSerializer.java spacewalk.git master: 885faab1b66a1da6d112326dfe360e897c11f611 > * In Spacewalk 1.3 release notes > (https://fedorahosted.org/spacewalk/wiki/ReleaseNotes13) is mentioned > > errata.publishAccordingToParents > > but there is no such function in documentation, nor in code. This is a mistake in the release notes text. The correct function name should have been: errata.publishAsOriginal > * configchannel.createOrUpdateSymlink ... documentation is hard to understand. > Revision -- null vs. optional? spacewalk.git master: 8cbbe969cffedb92c2c7d9388b1468b5aa0fd382 > * channel.software.getRepoSyncCronExpression > It is called CronExpression, but it returns quartz expression... spacewalk.git master: a5673cad3ee2c5c3da3a70ace1f10065260f4bc4 > * system.config.createOrUpdatePath > configchannel.createOrUpdatePath > - Maybe it's just me, but this looks like "inconsistency" at least: > > Having 5-th parameter > > {"contents":"Kwaaaak!\n", "contents_enc64":False, "owner": "root", > "group": "group", "permissions": "600", "binary": False} > > leads to { ..., 'contents': 'Kwaaaak!', ...}, while > > {"contents": "S3dhYWFhayEK", "contents_enc64": True, "owner": "root", > "group": "group", "permissions": "600", "binary": False} > > leads to { ..., 'contents': 'Kwaaaak!\n', ...}, (first one strips trailing > spaces/newlines, second-one not). Even if the inconsistency you're showing is a bad thing (which I'm not sure it is), this is not really an API documentation problem. > * Methods > system.comparePackages > system.comparePackages > presence of 'other_system' and 'this_system' seems dependent on > 'comparsion', > not mentioned in documentation so I'm not sure whether it is correct > behaviour or not. > (PackageMetadataSerializer?) This is OK. > * system.search.uuid --> Too easy to send malformed input and obtain error... > in documentation is no "exception thrown on ..." > Example of "bad" call: system.search.uuid(key,":") Not really a documentation issue: there may be other calls as well that would return a traceback in case you provide malformed input.
> > * Methods > > system.comparePackages > > system.comparePackages > > presence of 'other_system' and 'this_system' seems dependent on > > 'comparsion', > > not mentioned in documentation so I'm not sure whether it is correct > > behaviour or not. > > (PackageMetadataSerializer?) > > This is OK. Is it OK from both "behavioural" and "documentational" point of view? Additionally: * There happen to be "empty bullets" in description of parameters/returns, e.g. for activationkey.addEntitlements. Here is list of functions that I was able to find that suffer from this: activationkey.addEntitlements activationkey.create activationkey.create -- (both versions) activationkey.listActivatedSystems activationkey.removeEntitlements channel.listPopularChannels channel.access.setOrgSharing distchannel.listDefaultMaps -- total void...? kickstart.profile.comparePackages kickstart.profile.getKickstartTree kickstart.profile.system.checkConfigManagement kickstart.profile.system.checkRemoteCommands system.listLatestAvailablePackage * In comment for system.getVariables (xmlrpc/system/SystemHandler.java) should be characters "<" and ">" replaced by "<" and ">" html-entities ... or just do something that it won't cripple produced html-documentation. * ASCII arrows are also in xmlrpc/kickstart/profile/system/SystemDetailsHandler.java xmlrpc/serializer/ServerActionSerializer.java xmlrpc/system/config/ServerConfigHandler.java xmlrpc/system/SystemHandler.java xmlrpc/configchannel/XmlRpcConfigChannelHelper.java xmlrpc/configchannel/ConfigChannelHandler.java though those are not that big problem, as the do not look like tag-opening.
(In reply to comment #3) > * In comment for system.getVariables (xmlrpc/system/SystemHandler.java) > should be characters "<" and ">" replaced by "<" and ">" > html-entities > ... or just do something that it won't cripple produced html-documentation. > > * ASCII arrows are also in > > xmlrpc/kickstart/profile/system/SystemDetailsHandler.java > xmlrpc/serializer/ServerActionSerializer.java > xmlrpc/system/config/ServerConfigHandler.java > xmlrpc/system/SystemHandler.java > xmlrpc/configchannel/XmlRpcConfigChannelHelper.java > xmlrpc/configchannel/ConfigChannelHandler.java > > though those are not that big problem, as the do not look like tag-opening. fixed in spacewalk.git master: 3a2d61fefa63e6376c7808a93df9326b56d8adc7
(In reply to comment #4) > > fixed in spacewalk.git master: 3a2d61fefa63e6376c7808a93df9326b56d8adc7 Checkstyle fix e2b9efc78a48cf742e263b6075aa178b13a096ea.
Fixes for the following calls activationkey.addEntitlements activationkey.create activationkey.create activationkey.removeEntitlements spacewalk.git master: 16e3c9cf4b8bb1733c887ccd75e7f31711bffff9 bdf70d4f2adae79682013c26650c17f73a9b61b8
Fixes for activationkey.listActivatedSystems channel.listPopularChannels channel.access.setOrgSharing spacewalk.git master: c6d6cca008000a92877079d6a322a9aa57cbcb7c c4d0305842961ebe1e8182d814965e87267f5023 249d6e260f8e4d4a338f39acd7c6440d211baf39
Fixes for the remaining api functions, spacewalk.git master: 57605abb6d82f2e1a726193582d84f9600cc61d3 26b82e03690d2d3a882594088c763cff2eac8344 c97f20ef8d30c6dccdd4330d15733a7b05a89283 eadc117f6dd8733f719fb665e174d9d40f424fe0 cd7d326f523899eea9a7d3891d46f1c276f36893 5144d8b23360bc9f2094c19e3b377ebd455e72f8
spacewalk.git master: 137c28a32d8dfc9f280d0ce9766119a53e8a6a38
Moving ON_QA. Packages that address this bugzilla should now be available in yum repos at http://yum.spacewalkproject.org/nightly/
Spacewalk 1.8 has been released: https://fedorahosted.org/spacewalk/wiki/ReleaseNotes18