This forum is in READ-ONLY mode.
You can look around, but if you want to ask a new question, please use the new forum.
Home » development » Documentation » API Documentation needs work
API Documentation needs work [message #87729] Mon, 02 November 2009 23:47 Go to next message
clintv2  is currently offline clintv2
Messages: 2
Registered: November 2009
Location: Houston TX
Junior Member
This is a common problem with all frameworks in general and it causes the most grief at times.

Here is an example about the problem I am mentioning.

http://www.symfony-project.org/api/1_2/sfDateValidator

I think that the default behavior of this validator is a bit subjective to begin with. If you type in 11022009, it will just typecast your input to an integer and return it. Unless your a savant, your probably not going to enter in a unix timestamp on a website. Most applications will want to complain at the user at this point! That aside, most of your users will probably put the slashes.

How do you find this out from the documentation though? There has to be a default behavior, whether it be throwing an exception or whatever, but rarely is the default behavior documented. Options are usually poorly documented as well. Sometimes they are documented, but only in some base class and not in the place that you first look.

Now the good thing is that it is all open source and you can actually go browse the source, but upfront documentation would be nice. It really isn't fun diving through 5 or 6 abstraction layers to find something that could have just been documented up front.

I call this the magic box problem. It's wonderful when the magic box works but when it doesn't... what do you do. Any magic features need to be documented well.

Disclaimer: I am taking the date validator's functionality from second hand info and haven't analyzed the class that well but I did see the else (integer) section if no format is specified.

[Updated on: Mon, 02 November 2009 23:49]

Re: API Documentation needs work [message #87758 is a reply to message #87729 ] Tue, 03 November 2009 14:45 Go to previous messageGo to next message
halfer  is currently offline halfer
Messages: 9535
Registered: January 2006
Location: West Midlands, UK
Faithful Member
The API could be better documented, I agree. Nevertheless, symfony in my view is still one of the better documented open source frameworks - see the enormous effort that has gone into creating and maintaining Jobeet Smile

Feel free to raise a ticket on this (in the Development menu), linking to this discussion. Indeed there may be one already.


Remember Palestine
Re: API Documentation needs work [message #87861 is a reply to message #87729 ] Thu, 05 November 2009 01:29 Go to previous messageGo to next message
clintv2  is currently offline clintv2
Messages: 2
Registered: November 2009
Location: Houston TX
Junior Member
There is a lot of general "this is how you do things in symfony" documentation. I am actually talking more about the specifics.

Another huge annoyance is that anytime you good some symfony class you get 20 different mirrors hosting the same minimal documentation.

BTW I am not coming on here to complain so much as to notify you of a problem that does deter the user base.
Re: API Documentation needs work [message #87889 is a reply to message #87861 ] Thu, 05 November 2009 14:38 Go to previous message
halfer  is currently offline halfer
Messages: 9535
Registered: January 2006
Location: West Midlands, UK
Faithful Member
clintv2 wrote on Thu, 05 November 2009 00:29

BTW I am not coming on here to complain so much as to notify you of a problem that does deter the user base.

Thanks for doing so. The reason why I suggest creating a ticket is that the core devs (the people who would have the greatest say on the direction of the documentation effort) don't spend a lot of time on the forums (afaik, anyway). They tend to use the google groups instead; if you prefer you could always drop a line there, to the users group.


Remember Palestine
Previous Topic:error in Chapter 9 for 1.1 and 1.2
Next Topic:How to correct translations in Documentation ?
Goto Forum:
  

powered by FUDforum - copyright ©2001-2004 FUD Forum Bulletin Board Software