On Wed, 7 May 2008, Tobias Schlitt wrote: > On 05/07/2008 01:06 PM Derick Rethans wrote: > > > On Wed, 7 May 2008, Alexandru Stanoi wrote: > > >> - Huge docblock at the beginning of the file is annoying. We should think > >> about a way to include docs there. > >> + > >> +# I prefer to write longer docblocks to help a bit the people who want to > >> jump > >> + in without reading the tutorial first or asking on IRC. > > > I agree here, the classes' doc blocks should be informative. Some of the > > current ones in many components are quite useles as they don't really > > help the users to understand how to use a class. For the @mainclass > > classes, they should have a thorough overview including examples. > > I was not talking about removing the examples from the generated API > docs, but to outsource them from the source file. This makes editing the > source more convenient and still keeps the informative API docs.
But we can't do that yet, so an informative (and long) doc block is the way to go now. > >> - ezcFeedTools::prepareDate() should not accept DateTime objects. If it > >> receives them, this indicates bad code. > >> + > >> +# What if you assign a DateTime object to $feed->published for example? > >> Should > >> + the code throw an exception because the date was not a string or > >> timestamp? > > > DateTime objects should be supported here. How is it bad code if it > > receives them? > > If you already have a DateTime object, you should not call this method. > Its not good to just call a function and don't actually know what type > you currently have. Parsing whatever date value (string or timestamp) is > ok, but if you already parsed the date and try to parse it again, that > is not good. I disagree here. This method is called to accept whatever form of input, and make sure the returned data is a DateTime object. The method is automatically called when you set $feed->published and it makes much more sense to have this method handle *all* input instead of making another exclusion before the function is called. THis also makes it possible to support multiple types of DateTime objects if those would be added later. regards, Derick -- Components mailing list Components@lists.ez.no http://lists.ez.no/mailman/listinfo/components
