[documentation] Need CVS + Drupal Issues guidance: How to help fix API documentation formatting

[Steven Jones]

Hello,

api.drupal.org has a module (the api module) that parses directories
and converts the doxygen comments into lovely html for our viewing
pleasure. The complications arise however in what goes in those
directories:

Drupal core (of the appropriate version) is in the directory, so that
things like format_interval, and variable_set have documentation.
But hook_nodeapi for example won't be in core, because there is no
'hook' module in core to implement them, the 'hook' is just a
placeholder. So instead, there's a special bit of the contrib CVS repo
that has extra documentation for these 'phantom' functions. This gets
checked out to the directories parsed by a.d.o too.

So...if you want to change the documentation on a.d.o then you'll
either need to patch core, if that's where the content is coming from,
or patch the docs in the contrib repo.

If you want to patch core, you should create an issue for the 'Drupal'
project, and the 'documentation' component.
If you want to patch the docs contrib repo, create an issue for the
'Documentation Project', with the 'documentation in CVS' component.

Hope that helps!

On Mon, Jun 2, 2008 at 11:56 AM, Mr. Meitar Moscovitz <meitarm at gmail.com> wrote:
> Hi all,
>
> Surfing the docs issue queue today, I found an issue referring to a
> formatting fix for the API docs. I did a bit of searching and found
> this, which talks about how to make API documentation fixes:
>
> http://drupal.org/node/144223
>
> I don't have—or want, really—a CVS committer account, mostly because
> I've never used CVS in my life. (I use Subversion when I have to, but
> prefer git.) As a result, I'm not entirely sure how to go about
> progressing this issue:
>
> http://drupal.org/node/254522#comment-866484
>
> Seems the issue is fixed for Drupal 7 and CVS HEAD, so I'm betting
> it's not even a high-priority issue, but that's exactly the kind of
> issue I'd like to use to familiarize myself with the process. :)
>
> I submitted a (`diff -u`) patch against Drupal 6.2, which I uploaded
> to the comments of the issue report. What happens next?
>
> The "Updating API documentation" node seems to want me to use the
> "Drupal" project, but there isn't an obvious component in that project
> I can submit the issue against. The original submitter of the issue
> used the "Documentation" project and selected "Documentation in CVS"
> as the component, which is exactly what I would have done, not knowing
> any better.
>
> Thanks,
> --
> -Meitar Moscovitz
> Drupal: http://drupal.org/user/265715
> Personal: http://maymay.net
> Professional: http://MeitarMoscovitz.com
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/
>



-- 
Regards
Steven Jones