CiviCRM Community Forums (archive)

Hey SVN too!  lots of stalls in the API market aren't there?

I see the SVN doesn't have test examples for each of the api functions.

to Xavier's point - as the noob I'll defer on the best way to generate and maintain these parameters.  But I'd be willing to help get those parameters in, somewhere, somehow.

Mason - I guess the point is that there are lots of 'strands' to the api documentation. Each of the 3 forms of code generated documentation fulfills a slightly different purpose and to my mind they are each useful (because in each case the maintenance of them contributes to the integrity of the API - for example generating the tests also ensures that functionality in the tests won't break on upgrade).

There is probably also a need for more text (on the WIKI probably) explaining how to navigate the documentation & make sense of it.

There are loads of places you can usefully help but the question is - which one do you find useful / interesting / want to engage more with. If you pick an area we can start giving you more specific pointers.

For example, 'soft_credit_id' is an un-documented parameter for ('contribution', 'get) . To add it to documentation ideally it would be added to the function civicrm_api3_contribution_getfields - in much the same way as 'note' has been.

However, personally I wouldn't use it in my custom code unless I knew it was tested so give me some security - so ideally a test would also be written & added to api_v3_ContributionTest.

By adding one line to that test

        $this->documentMe($params,$contribution,__FUNCTION__,__FILE__, $subfile, $description);

An example would be generated in the examples folder.

(gad I don’t seem to be being notified of replies to forum threads I’ve posted in)

CiviCRM is such a great project and does some very clever things in a well thought out way… but I’m glad to see I’m not the wannabe Civicrm programmer who has struggled with coming up to speed.

It’s not because of lack of help from the core team, because I’ve had heaps of help and lots of questions answered in friendly helpful manner. (thanks!!)

Personally I find myself retreating into the relative clearly documented world of MySQL, PHP and to a lesser extent Drupal… which is not good, but at least I can be productive in this universe.

I think part of the issue is that the V3 API is only half the story – it gives a great entity get/create interface but there is still a lot of the API story that is missing or (just as hard for a newbie) scattered around in numerous places.

So when you realize where to look the V3 API is pretty good  , but compare with http://api.drupal.org/api/drupal there are a few gaps in the documentation    !

I understand time is limited and this is all volunteer effort, so it’s a shame to the effort not effectively channeled

code generated comments are going to be easiest to maintain, but are there doesn’t seem to be an easy doorway into helping with them currently – I would have happily have contributed some comments during my recent endeavors if it had be simple (and would still!)

which gets me thinking is there a better open source hosting service that allows easy management of contributed code??

Xavier got me using git hub, which seems ok, but I’ve go no-where near enough experience with open-source software development to be able to even know what to look for in an open-source host…

but I reckon the world of CiviCRM may really get a boost from:
-   a more-flexible open source repository with
-   encouragement to all coders (new and old) to contribute code comments and
-   a regular phpdoc output

thank Lobo,

open source repositories is definitely outside my area of experience so i'm happy to defer. the reason for my comment tho was one of my more knowledgeable aquaintences reaction to the news that our org is using svn - pretty much 'omg not subversion! use git, or hg or anything but svn'... like I said not my area, but this guy trouble shoots mysql installs for a living

the fly in the ointment of the 'submit a few good patches and then we'll trust with the keys to the car' strategy is that you put a significant barrier in front of newbies - (who are large in number, completely lost, starting from first principals and trying to reverse engineer the code and are therefore possibly excellent sources of code comments) and the act of adding some comments to the code

would wikipedia have achieved its depth if it had imposed similar barriers?

i understand this is code not narrative, but my understanding is that some of the other repositories manage contributions from "less trusted sources" a little better... just what i've heard

btw if give me the key ;-) you may get a few comments in return, but I have a bit too much smoke coming out of local machinery too promise any more :-) currently

touche, fair cop... i'm just trying to be clear about my own limitations and not making myself to be an expert, because i'm not!... but perhaps this post can start a conversation that may engage people with more experience

granted the wiki has low barriers - and perfect for user/admin, but some phpdoc comments in the code is much more sustainable and sensible for documenting the api (in the broader use of the term) - and would likely lend itself to better ongoing organisation.

As for projects using different rcs systems, they're all on wikipedia for what that's worth, but this page seems most salient: http://en.wikipedia.org/wiki/Distributed_revision_control

Lobo, I don't know if a different rcs is even worth considering, or if it is the way the tool is used rather than the tool itself, my point is that I'd have happily clarified some code with some phpdoc if able

just a thought that's all

:-)

Hi,

the steps to submit a patch for phpdoc code are basically:
1) Create a patch. More help on creating a patch here: http://drupal.org/patch, http://en.wikipedia.org/wiki/Patch_%28Unix%29
2) Open a http://issues.civicrm.org/jira/browse/CRM?report=com.atlassian.jira.plugin.system.project:roadmap-panel ticket and attach it

I'd be happy to follow a policy of always applying people's patches on PHP doc unless it is blatantly incorrect.

I just created a patch to add  'soft_credit_to' to the getfields function & improve the function comments to demostrate how

http://issues.civicrm.org/jira/browse/CRM-8662

As someone even newer at this that Erich, I think he sums it up for me:  there's stuff I want to contribute but its hard to even know how to (and all the threads of the API are a great example of why this can be hard, especially after wandering through the more complete Drupal API). I'm not really a programmer, a tool-user if you will but not the tool-maker and as such my field of view is spectacularly small!

Lobo - I like the idea of having some tasks labeled as "beginner" and I'd be a willing beginner.  I think a great first task would be API documentation (yes, I'm biased!)... its a good place to learn about how Civi works, its fairly contained (there are a limited number of APIs, and they have a lot of similarity).

In the meantime, I'll follow Eileen's instructions and see if I can make something happen there.

nice :-) all very positive

sorry that my ability to take on responsibility for any significant block of work is limited outside that of keeping my current project on track... or perhaps getting it on track... but an election cycle is immutable 

there are a few threads in the above conversation, and a few more related I'll try to pull out in the next week or two and start some separate discussions on