CiviCRM Community Forums (archive)

Eileen - did a quick fix, take a look at rev 31839.

Thx,
m

Ok - cool - so the link to the example is there now - I stuck in the inline tag too although I suspect you may have tried it and it may not work?

Yup, tried, nope, didn't work. I would say - for examples, good enough for now. If we figure out how to fix inline later on, we can quickly change it.

But the question is now whether it is a good idea - as Xavier pointed out the examples folder should probably go in the test directory

Yes and no. Tests have their own needs for the quantity of code, so displaying whole test case as an example is a bit non meaningful. Inline example has ability to limit the scope of displayed code to a piece designated by start and end line (given as parametrs to {@example}), but a) it doesn't work for us, b) tests will change and it will put the need to upfate line numbers every time something is modified within test. I would say - do this in api directory, of "fire and forget" basis. Since we're aiming at stability, it should be possible to write examples once. Additional argument - not every example should/needs to be run as test, so it doesn't belong in tests directory. On the other hand, the less code to maintain, the better - so if there is a way to come to terms with all of the above doubts, examples could be stored in tests dir as well.

Thx,
m

my recommendation is that we have  a folder called 'examples' either in api/v3/examples or test/api/v3/examples

and each operation gets it's own file

ActivityCreate.php
ActivityGet.php

with the functions

test_api_v3_activity_create(){
}

test_api_v3_activity_create_expectedresult(){
}

Then we don't need to muck around with line numbers

The arguments for in the tests dir is it brings people's attention to the test stuff. Alternatively the api dir may be more intuitive & obvious. Either way I can probably create some & move them fairly easily later. I think having a few more in place may suggest the best approach

Guys, I really don't follow you, we must be smoking some totally different things. :-)

@Eileen:
How does it differ from actual tests (apart from naming)?

@Xavier:
Generate what? Examples? And what XML schema has to do with API methods (apart from the list of return values)? :-)

Thx,
m

Michal - only differs from other tests in that it's written in a way designed to be more accessible as documentation (and hopefully to encourage others to submit patches)