This service will be undergoing maintenance at 00:00 UTC, 2017-10-23 It is expected to last about 30 minutes
Bug 811470 - API vs Documentation inconsistency
API vs Documentation inconsistency
Status: CLOSED CURRENTRELEASE
Product: Spacewalk
Classification: Community
Component: API (Show other bugs)
1.7
Unspecified Unspecified
unspecified Severity unspecified
: ---
: ---
Assigned To: Milan Zazrivec
Matej Kollar
:
Depends On:
Blocks: 820209 space18
  Show dependency treegraph
 
Reported: 2012-04-11 03:57 EDT by Matej Kollar
Modified: 2015-07-26 18:20 EDT (History)
2 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
: 820209 (view as bug list)
Environment:
Last Closed: 2012-11-01 12:22:06 EDT
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Matej Kollar 2012-04-11 03:57:56 EDT
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,":")
Comment 1 Milan Zazrivec 2012-04-12 08:11:53 EDT
(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.
Comment 3 Matej Kollar 2012-04-16 08:03:58 EDT
> >  * 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 "&lt;" and "&gt;" 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.
Comment 4 Milan Zazrivec 2012-04-27 12:57:11 EDT
(In reply to comment #3)
>   * In comment for system.getVariables (xmlrpc/system/SystemHandler.java)
>     should be characters "<" and ">" replaced by "&lt;" and "&gt;"
> 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
Comment 5 Jan Pazdziora 2012-04-30 09:31:47 EDT
(In reply to comment #4)
> 
> fixed in spacewalk.git master: 3a2d61fefa63e6376c7808a93df9326b56d8adc7

Checkstyle fix e2b9efc78a48cf742e263b6075aa178b13a096ea.
Comment 6 Milan Zazrivec 2012-06-01 13:48:54 EDT
Fixes for the following calls

activationkey.addEntitlements
activationkey.create
activationkey.create
activationkey.removeEntitlements

spacewalk.git master:

16e3c9cf4b8bb1733c887ccd75e7f31711bffff9
bdf70d4f2adae79682013c26650c17f73a9b61b8
Comment 7 Milan Zazrivec 2012-06-01 14:14:41 EDT
Fixes for

activationkey.listActivatedSystems
channel.listPopularChannels
channel.access.setOrgSharing

spacewalk.git master:

c6d6cca008000a92877079d6a322a9aa57cbcb7c
c4d0305842961ebe1e8182d814965e87267f5023
249d6e260f8e4d4a338f39acd7c6440d211baf39
Comment 8 Milan Zazrivec 2012-06-04 14:51:43 EDT
Fixes for the remaining api functions, spacewalk.git master:

57605abb6d82f2e1a726193582d84f9600cc61d3
26b82e03690d2d3a882594088c763cff2eac8344
c97f20ef8d30c6dccdd4330d15733a7b05a89283
eadc117f6dd8733f719fb665e174d9d40f424fe0
cd7d326f523899eea9a7d3891d46f1c276f36893
5144d8b23360bc9f2094c19e3b377ebd455e72f8
Comment 9 Milan Zazrivec 2012-06-05 03:37:30 EDT
spacewalk.git master: 137c28a32d8dfc9f280d0ce9766119a53e8a6a38
Comment 10 Jan Pazdziora 2012-10-30 15:27:13 EDT
Moving ON_QA. Packages that address this bugzilla should now be available in yum repos at http://yum.spacewalkproject.org/nightly/
Comment 11 Jan Pazdziora 2012-11-01 12:22:06 EDT
Spacewalk 1.8 has been released: https://fedorahosted.org/spacewalk/wiki/ReleaseNotes18

Note You need to log in before you can comment on or make changes to this bug.