Lisa - I should have said to add to the documentation for file_match, that care has to be taken with what functions are called whilst doing the find_first, find_next sequence e.g. calling file_list_field (as Clark was trying to do) doesn't work because file_list_field does a find_first.
[EDIT - whilst I wrote this post, Clark pointed this out too.]
ClarkI think I have to revise my comments slightly about the slick API documentation. I think your comments are all valid - I was thinking more of what's involved in customising Slick source.
I suspect if you could give specific examples of what you're trying to do and where the API docs are lacking, SE would at least consider improving the help info at some stage, if it related to things that more than just one or two people were trying to do.
However I have to qualify this as follows. I know you gave the example of the problem with file_match - I think this is mainly in the category of oversight and perhaps a little in the category that the API doc info isn't written with as much discipline as some other APIs (what's the Visual studio customisation API like?). I suspect very few people actually report problems with the slick docs - I really think slick help info would benefit from having its own forum here that people can quickly and visibly report problems/ errors to.
You also gave the example of the tagging API. This API looks hard to use as you say, but I get the feeling there are very few people who would want to use it - yet SE goes to all the trouble of writing it as Slick C code (instead of C++) and documenting a large number of functions without giving an overview of how to go about using it all, and, as you say, of how it relates to the slickedit environment. I remember Gary Ash reporting he had difficulties using the tagging API
http://community.slickedit.com/index.php?topic=224.msg852#msg852and after several weeks
, Dennis responded - but a lot better late than never!
Same goes for the XML API - there's no overview or complete example of how to create an XML file. Probably a file like hotfix.e can be used to see how to read an XML file, but from a 5 minute skim through the result of searching for _xmlcfg_ it wasn't obvious to me which code to look at to see how to create a new XML file. Perhaps someone who is familiar with xml APIs would find it easy.
Regarding missing parameter info - I guess SE would probably add the missing info eventually if the problem is reported. Regarding missing examples, maybe SE would consider adding more examples where they're really needed, but these probably take quite a bit of time and I guess SE is only a relatively small company.
So to answer your question, "what's the secret" - I think most people try to find examples in the existing source and probably spend quite a while doing it sometimes. Since SE want people to be able to use their API without tearing their hair out, some specific examples of what "typical" people are trying to do and where the docs fail might help. I'm not sure whether the tagging API would have enough people wanting to use it to justify SE documenting it better - I'm just guessing though (as I said, they went to all the trouble of "publishing" it. ).
Graeme
