Ariel , I can understand your concern. As the implementation specific need to be used by these API, especially for these "PropertyValue" paramether. >From the end point user view, it should be part of API docs. You mentioned "implementation specific: the list of filter supported by implementation > A may not match those by implementation B", from my understanding, this maybe is different version, the API docs also need corresponding version.
Jürgen, provide realted information link to API docs can let user easy to user these API, thus will much friendly and easily to use them. Thanks. DongJun Zong 2012/8/16 Jürgen Schmidt <jogischm...@gmail.com> > 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 > >
