Documentation and book

[e_mason]

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.

[xavier]

Hi,

The examples are generated by running the test, not checked in.

Definitely should be somewhere, not sure either where, but sure we'll find a way to present them better.

X+

[Eileen]

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.

[fen]

The API explorer is great - particularly helpful is the ability to enter param=value pairs and see the results immediately.  But discovering the correct params still requires searching through code (and forums).

In the interest of clearer documentation, there's three issues I've noticed with the params display in /ajax/doc/ :

• It would be easier (for me) to have the actual field names appear rather than the print names, such as "actual_amount" instead of "Actual  Amount"
• Not all the available params show up, for example, 'soft_credit_to' doesn't show up in "Contribution >> create".  In a conversation on this subject on IRC earlier, @xavier_d asked: "is there a generic way to get the extra fields that are managed by the BAO on the top of the ones from the DAO?"  (I don't know the answer.)
• Sometimes the names are transparently "shadowed" to prevent conflicts, e.g., in "Pledge >> create" you have to use 'pledge_contribution_type_id' as 'contribution_type_id' is ignored (discussed in http://forum.civicrm.org/index.php?topic=20312.0)

I've done a (admittedly small) bit of looking but haven't found how to correct any of these issues yet, but if someone can point me to how I could make some contributions here, I will help as I can.

[Erich Schulz]

(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

[Donald Lobo]

all valid points, that i dont think many folks will argue against (or at least i hope not).

a few comments:

1. the upcoming code/book sprint hopefully will update and improve the API / code docs a bit more

2. To submit any patches (code or doc), the steps are:

* File an issue and attach a patch
* Most issues with attached patches tend to get applied for the next point release (i.e. its in the distributed code base in 3-6 weeks!)
* Once u file a fair number of the above, we are fairly generous in granting commit rights to svn

svn as an open source repository is fairly flexible and meets our needs. We have multiple folks committing to it so thats not the bottleneck

lobo

[Erich Schulz]

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

[Donald 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

If we were starting today, yes, we'd probably use git or one of the modern DVCS. However we have a few years worth of stuff in svn and migrating requires a few folks to help lead, plan and implement the migration. Wanna lead it?

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?

The civicrm wiki has pretty low barriers (create an account) and then go edit stuff. You'd be surprised as to the number of "user" contributions / edits we get and in the civi community, based on our experience # of users/admins >>>> # of coders
 

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

Please give us examples of the other projects with specifics. We'd be happy to learn from and see how we can improve on what / how we are doing things. Statements like: From what i've heard / A good friend of a friend who knows everything really does not help us (or you)

lobo

[Erich Schulz]

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

:-)

[Donald Lobo]

You raise quite a few valid points. In some of them, specifically the below:

* Migrate to GIT
* List of simple tasks for beginner coders to address
* improve phpdocs and simplify the patch process for improving this

the next task is for someone to help take the lead and push it forward. Would be great if you can follow up and help with one or more of the tasks above.

Documenting thoughts are great, but ultimately someone needs to implement those thoughts Looking forward to your contributions

lobo

[Eileen]

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

[Eileen]

And, on the basis that any API behaviour that isn't tested should be treated as a random co-incidence not a feature, and under no circumstances documented or relied on in production code I also added a test.

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

[e_mason]

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.

[Donald Lobo]

Lets have a chat monday morning on IRC (6:00 am or later PDT which is also fairly reasonable time in europe, 3:00 pm and the east coast) and figure out in what format and what makes sense for a beginner task list.

Erich S sent me an example of an existing project:

http://www.phpmyadmin.net/home_page/improve.php

We could potentially use that and others for ideas. Would be great if folks interested could show up and offer to help get this up and running.

lobo

[Erich Schulz]

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