On 8/16/12 11:40 AM, Ariel Constenla-Haile wrote: > Hi, > > On Thu, Aug 16, 2012 at 05:25:15PM +0800, dongjun zong wrote: >> 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. > > This example simply shows some constant values that are used for ActionX > and ActionY. We also have constant values in AOO API, see for example > http://www.openoffice.org/api/docs/common/ref/com/sun/star/frame/XComponentLoader.html#loadComponentFromURL > > [in] long SearchFlags are > http://www.openoffice.org/api/docs/common/ref/com/sun/star/frame/FrameSearchFlag.html > > Constant values can be part of an API specification. But in this thread > you where asking to document filter names, this is completely different. > The API specification only says it's a string, with the *internal* > filter name. It is imposible to list here all posible strings, not > only/mainly because they are too much, but because this is > implementation specific: the list of filter supported by implementation > A may not match those by implementation B, the list is not a constant > set of values (besides, AOO API does not allow string constants). > >
Ariel is completely correct with his argumentation whereas I can understand DongJun Zong that it is hard to find the necessary information. Ariel pointed out that it would make sense to collect and document the implementation specific data in a separate place and add changes on demand for different versions. And yes we could add a link into the reference documentation to point to this data. I think we have done this from time to time and the information is available somewhere (I have to search as well). Well it's probably not complete but definitely a good start of course. We can try to collect the infos we had already and can consolidate them in one place where we link to from the API docs. Feel free to start with this work ;-) It's not the only place where somebody can start quite easy to contribute something very useful to the project. A good place is probably under the API section in the wiki, we can discuss the place and the structure... Juergen
