If worried about API documentation is too long, provide a link in API doc is need. Paramether valid value list is basic part of API docs.
Please see a MS office API docs for example " http://msdn.microsoft.com/en-us/library/gg264840";. It list all the values could be use by the method. 2012/8/16 Ariel Constenla-Haile <arie...@apache.org> > Hi > > On Thu, Aug 16, 2012 at 04:31:13PM +0800, dongjun zong wrote: > > I think I can't agree with you. I had used MS Office VBA APIs before, in > > their VBA API docs, include this kind of information. > > MS may do stupids things, should we follow them just because it's MS? > http://www.nizkor.org/features/fallacies/appeal-to-authority.html > > > Besides compare with > > MS Office API docs, I think as public API docs, should contain the > > information for every method parameter valid list. Thus when I use a > > method, I only need to read the API docs. > > AOO API docs have on the top a "Devguide" link. This should guide you to > an explanation and some implementation specifics. Of course, this can be > improved, and we could list every filter for FilterName and every > FilterOption and FilterData for every specific filter, but this cannot > be included in the API docs, it's implementation specific, a filter > implementation is free to change it. May be you didn't get that all the > tables in > > http://wiki.openoffice.org/wiki/API/Tutorials/PDF_export#PDF_Export_filter_data > are the implementation of FilterData for this specific filter, the PDF > export filter. > > Now consider all the filters available in AOO, documenting each one in > the API documentation is a nonsense: besides breaking the notion of > implementation vs. specification, it will make the documentation too > long, I doubt MS does something similar. > > > Regards > -- > Ariel Constenla-Haile > La Plata, Argentina >
