Attached is a first draft of whole subscriptions API documentation.

Blessings!

CommentFileSizeAuthor
#10 subscriptions-apidoc-0.5.patch18.08 KBdevelcuy
#5 subscriptions-apidoc-0.4.patch6.58 KBdevelcuy
#3 subscriptions-apidoc-0.3.patch34.67 KBdevelcuy
#2 subscriptions-apidoc.225648.2.patch26.42 KBsalvis
subscriptions-apidoc.patch26.22 KBdevelcuy

Comments

develcuy’s picture

develcuy commented

Please take a look to the live API site http://develcuy.elblog.de/subscriptions_og/api/subscriptions

God bless you.

salvis’s picture

salvis
he/his
commented
Status: Postponed (maintainer needs more info) » Reviewed & tested by the community
StatusFileSize
new subscriptions-apidoc.225648.2.patch26.42 KB

Very nice, THANK YOU!!!

I've reviewed your texts, done some editing and committed it to our internal repository. Please apply this patch to BETA11, so that we're in sync again.

I want to put an acknowledgment into the README.txt, something like

API documentation by develCuy.

Is it your contribution alone or should I also mention sponsoring by gustav, and if, how?

develcuy’s picture

develcuy commented
StatusFileSize
new subscriptions-apidoc-0.3.patch34.67 KB

This is an effort sponsored thanks to Gustav, I just doing what I have to.
I'm waiting for Gustav reply to suggest some text for the acknowledgment.

Attached is a new version of API documentation based on the one you review. I've added a main page with the current description of subscriptions module, so, please review again there: http://develcuy.elblog.de/subscriptions_og/api/subscriptions.

Blessings!

salvis’s picture

salvis
he/his
commented

I'm sorry, I can't apply your patch anymore, because my files have changed in the meantime. Can you make a diff relative to #2? That might have a chance to apply.

develcuy’s picture

develcuy commented
StatusFileSize
new subscriptions-apidoc-0.4.patch6.58 KB

ok salvis, hope this help.
Blessings!

gustav’s picture

gustav commented

develCuy: thanks for providing this documention. As we just discussed privately, this does not constitute a documentation of the subscriptions API. The API documentation should consists of a documentation of the hooks that a subscriptions plugin module needs to implement? For each hook we need a description of the arguments that are passed and the return value that is expected? This should be similar to how core drupal hooks are documented at http://api.drupal.org/api/group/hooks/5. In our private discussion we decided that the best way for you to provide such an API documentation is to provide good documentation for the implementations of these hooks in the subscriptions_og code so that those can serve as example implementations.

Salvis: credit for this documentation and for the subscriptions_og plugin should certainly go to develCuy. If you like you can mention that his work is sponsored by www.transit.york.ac.uk.

salvis’s picture

salvis
he/his
commented

@develCuy: yes, this worked -- thanks!

@gustav: ok, I'll list it in the README.txt. Thank you!

Documenting the API in the context of subscriptions_og is a good idea, I'll point to it.

develcuy’s picture

develcuy commented

salvis, I've added following groups to documentation: form, hooks, themeable. Please take a look at: http://develcuy.elblog.de/subscriptions_og/api/subscriptions. I would like to merge those changes to your current code. To easy maintenance task, if you agree, please provide a patch with your latest version of subscriptions module files, so I can provide a new patch with latest changes on documentation.

Blessings!

salvis’s picture

salvis
he/his
commented

No, I don't want to post a intermediary version, because it might not have the expected quality and cause confusion if someone applies it. But the patch mechanism is amazingly robust, so just post your changes and I'll see whether they apply.

develcuy’s picture

develcuy commented
Status: Reviewed & tested by the community » Needs review
StatusFileSize
new subscriptions-apidoc-0.5.patch18.08 KB

Ok Salvis, here is a new version of API documentation relative to 0.4.
There are some details to keep in mind in order of get api.module's parser working well:

Example 1:
WRONG:

function myfunc()
{
  ...
}

FINE:

function myfunc() {
  ...
}

Example 2:
WRONG:

/**
 * Fuction description
 */

function myfunc() {
  ...
}

FINE:

/**
 * Fuction description
 */
function myfunc() {
  ...
}

Blessings!

salvis’s picture

salvis
he/his
commented

I've been able to apply your patch and I've fixed all Coder issues (found 1 of the type you describe).

This will be in BETA12.

salvis’s picture

salvis
he/his
commented
Status: Needs review » Active
gustav’s picture

gustav commented

salvis: can you please always commit your latest code to CVS, even in between releases? It is good and common drupal practice to make on commit for every change and every fixed issue. Makes it easier for others to follow the development of the code. Thanks.

salvis’s picture

salvis
he/his
commented

You can get the latest snapshot from the repository mentioned in http://drupal.org/node/187186#comment-618459, but please don't raise any issues here about what's there.

gustav’s picture

gustav commented

Having the code in a separate repository is very inconvenient. Why do you not use the drupal cvs for the development of this module? I vaguely remember that you explained this to me once before but I forgot the answer. So simply ignore my question if you like. But if you could move to using the drupal cvs it would make it easier for other developers.

salvis’s picture

salvis
he/his
commented

chx is the maintainer, not I. And I'm quite happy to use svn rather than cvs. Our history is in that other repository and it's unlikely that we'll change the way we work as we're getting close to release, but for the reasons you cite I favor moving to d.o when 2.0 is out.

salvis’s picture

salvis
he/his
commented
Version: 5.x-2.0-beta11 » 5.x-2.0-beta12
Status: Active » Fixed

@develCuy: it's all merged in BETA12, and I ran it through Coder, so there should be no more api.module parsing problems.

develcuy’s picture

develcuy commented

@salvis: Thank you!, I've reviewed code and looks perfect.

I'm will reopen this issue later because gustav and me are working on a more detailed and cleaner documentation at least for hooks: http://drupal-contrib.org/subscriptions_og/node/18.
And about doxygen, I've added @defgroup definitions directly into subscriptions.module so that let API module parse a nice frontpage like this one: http://api.drupal-contrib.org/api/subscriptions. Without @defgroup, there is not chance for API module to construct topics, ie: http://api.drupal-contrib.org/api/group/hooks/subscriptions.

If you removed @defgroup because duplicates those already defined in drupal core, I suggest to let me use alternative names, by example:

/**
 * @defgroup subscription_form Form functions (Subscriptions)
 * @{
 * Functions to enable the processing and display of HTML forms for Subscriptions module.
 * 
 * Please refer to @link http://api.drupal.org/api/file/developer/topics/forms_api_reference.html/5 online reference @endlink.
 */
/**
 * @} End of "defgroup subscription_form".
 */

Same for menus, themes and hooks

And then use both doxygen groups, as follows:

/**
 * Some kind of form
 *
 * @ingroup form
 * @ingroup subscription_form
 */
function subscriptions_xxx_form(){
  ...
}

Happy Holy Friday(it is still March 21 in Perú) and Blessings!

salvis’s picture

salvis
he/his
commented

Wow, great work on http://api.drupal-contrib.org/, develCuy!

I'm not aware of having removed anything — did you post it?

However, I did see

Use Doxygen Modules (@defgroup, @ingroup, @addtogroup, see "Limitations and hints" below) sparingly.

in http://drupal.org/node/1354#contrib and wondered...

Yes, feel free to reopen this issue, of course.

Happy Holy Friday and Blessings to you, too!

Anonymous’s picture

Anonymous (not verified) commented
Status: Fixed » Closed (fixed)

Automatically closed -- issue fixed for two weeks with no activity.