3

Ok,

I was eagerly awaiting the release of subsonic 3.0 to use as my low-level data layer, and now its out. I'm currently using the ActiveRecord templates (having tried both the repository and advanced templates) and I have one HUGE request and a few questions:

Request: Other than bug fixes, Rob please spend the time to provide documentation. I don't mean 5 examples, I mean API complete documentation. Here's why:

I'm testing subsonic by writing ASP.NET MembershipProvider and RoleProvider classes and simple questions continually slow me up using subsonic:

Q. Assuming I have a class 'User' and I update/save/delete a record using

user.Save();

I need information on how to get success/failure? Do I look for an exception on failure or can I get a count of 'affected' records (old school?)

Q. If I get an exception, which exception(s) can I expect?

I'll have more issues, but I really believe a good functional API documentation would solve the problem.

If the answer is 'read the source code', then I'm sure you're going to chase quite a few developers away from subsonic. I really want to use the library, but the point is "use" the library, not reverse engineer it.

-Jeff

Adam Cooper
  • 8,077
  • 2
  • 33
  • 51
Jeff
  • 121
  • 1
  • 8

3 Answers3

2

Q. I need information on how to get success/failure? Do I look for an exception on failure or can I get a count of 'affected' records (old school?)

If it doesn't throw an exception then it's worked

Q. If I get an exception, which exception(s) can I expect?

You can expect a DbException

Adam Cooper
  • 8,077
  • 2
  • 33
  • 51
  • Thanks, it seems obvious but I was unsure if Rob was using custom exception classes for Subsonic. – Jeff Jul 17 '09 at 20:14
2

We don't use custom exceptions. I spent 5 weeks writing docs - so yah I did spend some time on this. You could also find your answer there as well: http://subsonicproject.com/docs

  • I've seen your doc pages Rob and there's nothing wrong with them, but not enough and its certainly not organized enough. I understand limited resources and the complexity of documentation, I've done it myself. Tutorials and examples are great to get going, but nit-picky api reference is what would be amazing. I'd even accept good comments that generate auto-doc type information. Simply and easy place to lookup function calls, parameters and what does it do. Still, thanks for a great product, the more I use it, the more I enjoy it. -Jeff – Jeff Jul 19 '09 at 13:14
  • 2
    Open Source isn't supposed to be one person trying to make something "acceptable" to others. I'm not picking on you - I'm not trying to be a jerk either. I need help and I find that people have (for the most part) preferred to complain rather than dig in and help out. It's the landscape. –  Jul 21 '09 at 04:16
0

3.0 is a little too buggy for me so far. I think I am going back to 2.x for now, thanks for all the hard work though.