http://bugzilla.spamassassin.org/show_bug.cgi?id=3438 ------- Additional Comments From jm@jmason.org 2004-06-02 17:13 -------
Subject: Re: Conflicting API documentation
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
>a PML object is returned so that people can do more if they want to, but
>I'm not really sure what the point is to that. does anyone actively use
>PML? the only thing I found was PMS and sa-learn calls did_learn(),
>which could easily be turned into a return value from M::SA::learn --
>then we could get rid of PML.
It's good OO practice to have an object returned in this case, similar
to how the PerMsgStatus object works. That's what PerMsgLearner
is there for; a public "state of that learn request" return type.
We could alternatively return a "did_learn" bool from
M::SpamAssassin::learn() -- but what happens then if we need to provide
*more* info to callers, in the same way the PMS has additional methods
beyond get_hits(), such as get_report(), etc.? hence, better to have an
object, so we can increase the data that gets returned without having to
break old APIs.
>alternately, the idea is that like PMS, PML lets people generate the
>object using a static API, and then they can do stuff with it if they
>want to or just call finish. as such, they should call M::SA::learn()
>with only the message as a parameter (per the docs) and then they can
>call learn_spam, learn_ham, etc.
this isn't a good plan. Better for PerMsgLearner to be the returned
"state of your learn request" object, and not reusable.
The real problem is purely that the (internal) APIs on PerMsgLearner
are being documented in POD sections. they shouldn't be -- or at
least it should be made clear that those aren't public APIs.
I have a patch for this -- uploading in a sec...
- --j.
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.4 (GNU/Linux)
Comment: Exmh CVS
iD8DBQFAvmztQTcbUG5Y7woRAh4jAJ0SctAv+yKYPy52zhwrbIQTUm1IQACgt946
rAXJdq8eudkVHdIhJFz9m8I=
=FeU+
-----END PGP SIGNATURE-----
------- You are receiving this mail because: -------
You are the assignee for the bug, or are watching the assignee.