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

[Mr. Meitar Moscovitz-2]

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/

[Fernando P. García]

Hello Meitar:

It concerns the current available resources in drupal.org, and this certainly should be improved but may take a while because is in current plas for rebuilding.

So, I suggest to extend API module which stores api data to database, then we should be able to edit descriptions and make suggestions ala l10n_server(ie: look at l10n.drupal-contrib.org).

Blessings!

On Mon, Jun 2, 2008 at 5:56 AM, Mr. Meitar Moscovitz <meitarm@...> 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/

--
Fernando P. García, http://www.develcuy.com
Developer - Analista de Sistemas
[phone], Mz. P Lt. 30 1et Urb. Pachacamac - VES, Lima - Perú

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[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@...> 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
--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Steven Jones]

Enabling comments on a.d.o would probably be a huge help, but the
documentation of Drupal is scattered enough. We should put more
resources into consolidating docs into one place rather than opening
new avenues to create different forms of documentation (IMHO).

On Mon, Jun 2, 2008 at 6:11 PM, Fernando P. García
<fernando@...> wrote:

> Hello Meitar:
>
> It concerns the current available resources in drupal.org, and this
> certainly should be improved but may take a while because is in current plas
> for rebuilding.
>
> So, I suggest to extend API module which stores api data to database, then
> we should be able to edit descriptions and make suggestions ala
> l10n_server(ie: look at l10n.drupal-contrib.org).
>
> Blessings!
>
> On Mon, Jun 2, 2008 at 5:56 AM, Mr. Meitar Moscovitz <meitarm@...>
> 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/
>
>
>
> --
> Fernando P. García, http://www.develcuy.com
> Developer - Analista de Sistemas
> [phone], Mz. P Lt. 30 1et Urb. Pachacamac - VES, Lima - Perú
>
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/
>

--
Regards
Steven Jones
--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Mr. Meitar Moscovitz-2]

Hi Steven,

On Jun 3, 2008, at 9:47 AM, Steven Jones wrote:
> […]

> 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!


Thanks, that does help. In fact, based on your feedback I was about to  
go on over to my comment again (at http://drupal.org/node/254522#comment-866484 
  ) and put the issue in the right queue, but I see it's been done by  
someone else already.

Either way, now I know what the proper places for things like this  
are. 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/

[Angela Byron-4]

Mr. Meitar Moscovitz wrote:

> Either way, now I know what the proper places for things like this  
> are. Thanks!

Just as a general statement, Meitar, you're asking really great
questions that I'm sure all newcomers to the docs team are going to
struggle with. How would you feel about making a "Documentation
Contribution FAQ" or something like that that, which contains a list of
the questions you asked and the answers you've gleaned from the list, in
words that a fellow new contributors like yourself could understand? I'd
be happy to proof-read it for you, if you'd like.

You don't have to, of course, but it just seems like it'd be great to
get these things written up somewhere so the *next* time it becomes "Oh,
that's covered in the FAQ at <link>. See question #2." :)

-Angie
--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Sean Burlington-3]

Steven Jones wrote:
> 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.
>

Slight aside (this doesn't address CVS issues)

...hook_nodeapi isn't in core - but node_invoke_nodeapi is

- and this is what defines the hook

I wonder how hard it would be to alter the api module to recognise hooks
in this way - and then to add the references (eg forum_nodeapi)

At the moment the only link between these is generated by the comment
"implementation of hook_nodeapi"

I might have a look at doing this...

--

Sean Burlington

www.practicalweb.co.uk
company number 06427950
--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Steven Jones]

I wouldn't say that node_invoke_nodeapi 'defined' the nodeapi hook. It
invokes it, because module_invoke_all can't handle references.

But I think that for people looking for how to use the nodeapi hook
are much more likely to tap 'hook_nodeapi' into a.d.o. You don't need
knowledge of how the hook is invoked to implement it, you just need to
know what parameters you get etc.

On Tue, Jun 3, 2008 at 10:55 AM, Sean Burlington
<sean@...> wrote:

> Steven Jones wrote:
>> 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.
>>
>
> Slight aside (this doesn't address CVS issues)
>
> ...hook_nodeapi isn't in core - but node_invoke_nodeapi is
>
> - and this is what defines the hook
>
> I wonder how hard it would be to alter the api module to recognise hooks
> in this way - and then to add the references (eg forum_nodeapi)
>
> At the moment the only link between these is generated by the comment
> "implementation of hook_nodeapi"
>
> I might have a look at doing this...
>
> --
>
> Sean Burlington
>
> www.practicalweb.co.uk
> company number 06427950
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/
>

--
Regards
Steven Jones
--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Mr. Meitar Moscovitz-2]

On Jun 3, 2008, at 12:03 PM, Angela Byron wrote:

> Mr. Meitar Moscovitz wrote:
>
>> Either way, now I know what the proper places for things like this  
>> are. Thanks!
>
> Just as a general statement, Meitar, you're asking really great  
> questions that I'm sure all newcomers to the docs team are going to  
> struggle with. How would you feel about making a "Documentation  
> Contribution FAQ" or something like that that, which contains a list  
> of the questions you asked and the answers you've gleaned from the  
> list, in words that a fellow new contributors like yourself could  
> understand? I'd be happy to proof-read it for you, if you'd like.

That makes sense to me. I'm sure most of the answers to such questions  
already exist in many places, but in all the places that I've found  
what turned out to be correct answers, they were pretty brief and hard  
to interpret. For instance, here, in "Updating API documentation" http://drupal.org/node/144223 
  there's a short section headlined "Code" that has two sentences in it:

> All documentation for core functions, constants, and files are  
> automatically generated from the core modules in Drupal. […] To  
> update these, you must submit a core patch to edit the Doxygen  
> comments of the code in question.


The text "submit a core patch" is a link to the http://drupal.org/node/add/project-issue/drupal 
  page, which is far from explanatory for someone like me (until  
yesterday, when Steven clued me into the details). Better, IMHO, would  
be a paragraph or two (tops) with appropriate links embedded in  
natural text to places such as "Doxygen formatting conventions" (http://drupal.org/node/1354 
) and so forth, so the reader doesn't have to reach for the search box  
in a ridiculous number of browser tabs. :)

So I guess my question is, do you think there's really a need for a  
FAQ, or should I just spend a little while going through some of the  
child pages to "Contributing to documentation" and fleshing them out  
further?

Of course, I could always do *that*, and then *also* compose a list of  
all the questions I'm asking, run them by you or a mailing list  
archive search to see how frequent they are, and then post brief one-
liners with appropriate links in a new "Contributing to documentation  
FAQ", as well….

> You don't have to, of course, but it just seems like it'd be great  
> to get these things written up somewhere so the *next* time it  
> becomes "Oh, that's covered in the FAQ at <link>. See question #2." :)
>
> -Angie


I didn't have to ask to join the Drupal docs team either, now did I? ;)

Cheers,
--
-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/

[Sean Burlington-3]

Steven Jones wrote:
> I wouldn't say that node_invoke_nodeapi 'defined' the nodeapi hook. It
> invokes it, because module_invoke_all can't handle references.

My understanding is that creating a function called

mymodule_invoke_dosomething()

will cause Drupal (via module_invoke_all() ?) to call functions in other
modules called othermodule_dosomething()

Is there another step in hook creation that I'm missing?


> But I think that for people looking for how to use the nodeapi hook
> are much more likely to tap 'hook_nodeapi' into a.d.o. You don't need
> knowledge of how the hook is invoked to implement it, you just need to
> know what parameters you get etc.
>

I agree - I'm just wondering if we (maybe me) could automate the
creation of the hook_nodapi page.

- and at the same time look for functions that are implementations of
the hook so that the hook_nodapi references has links to all the places
the hook is used.

This would be especially useful for my use of the API module on sites I
work on - where I would be able to look (for example) for all the places
  the site uses hook_form_alter().



--

Sean Burlington

www.practicalweb.co.uk
company number 06427950

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Steven Jones]

Hi,

> My understanding is that creating a function called
>
> mymodule_invoke_dosomething()
>
> will cause Drupal (via module_invoke_all() ?) to call functions in other
> modules called othermodule_dosomething()
>
> Is there another step in hook creation that I'm missing?

You need to call module_invoke_all giving the name of the hook that you want to invoke as the first parameter, and the rest of the parameters of the hook. It will return a merged array of all the results from those modules that implement that hook. See: http://api.drupal.org/api/function/module_invoke_all/6

You may want to put the call to module_invoke_all in a wrapper function in your module, which mymodule_invoke_hookname would be a good place, but there's no hard and fast rule AFAIK.

> I agree - I'm just wondering if we (maybe me) could automate the
> creation of the hook_nodapi page.

It is! a.d.o checks out a file from CVS, http://cvs.drupal.org/viewvc.py/drupal/contributions/docs/developer/hooks/, and that's where the http://api.drupal.org/api/function/hook_nodeapi/6 page comes from.

> - and at the same time look for functions that are implementations of
> the hook so that the hook_nodapi references has links to all the places
> the hook is used.

They'll need to be named modulename_nodeapi so finding implementations is fairly trivial, just use the search box on a.d.o and type in: "_nodeapi"

Also, we're getting a little off-topic here :-D

On Tue, Jun 3, 2008 at 12:22 PM, Sean Burlington <sean@...> wrote:
> Steven Jones wrote:
>> I wouldn't say that node_invoke_nodeapi 'defined' the nodeapi hook. It
>> invokes it, because module_invoke_all can't handle references.
>
> My understanding is that creating a function called
>
> mymodule_invoke_dosomething()
>
> will cause Drupal (via module_invoke_all() ?) to call functions in other
> modules called othermodule_dosomething()
>
> Is there another step in hook creation that I'm missing?
>
>
>> But I think that for people looking for how to use the nodeapi hook
>> are much more likely to tap 'hook_nodeapi' into a.d.o. You don't need
>> knowledge of how the hook is invoked to implement it, you just need to
>> know what parameters you get etc.
>>
>
> I agree - I'm just wondering if we (maybe me) could automate the
> creation of the hook_nodapi page.
>
> - and at the same time look for functions that are implementations of
> the hook so that the hook_nodapi references has links to all the places
> the hook is used.
>
> This would be especially useful for my use of the API module on sites I
> work on - where I would be able to look (for example) for all the places
>  the site uses hook_form_alter().
>
>
>
> --
>
> Sean Burlington
>
> www.practicalweb.co.uk
> company number 06427950
>
> --
> Pending work: http://drupal.org/project/issues/documentation/
> List archives: http://lists.drupal.org/pipermail/documentation/
>



--
Regards
Steven Jones

--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Steven Jones]

Hi,

I'd imagine writing a FAQ by yourself would be a huge undertaking, instead, why don't you create an issue in the queue (documentation project) and just list any questions that you can think of, others can do the same and then gradually we can move them over into handbook pages. If we make each question its own page then the handbook theming will give us a nice list of all of them on the parent page.

If there were a list of 'Unanswered FAQs'  then I'd happily spend ten minutes every now and then writing an answer to one and adding it. If other's did the same we'd get a high quality FAQ list in no time.

On Tue, Jun 3, 2008 at 12:11 PM, Mr. Meitar Moscovitz <meitarm@...> wrote:

On Jun 3, 2008, at 12:03 PM, Angela Byron wrote:

> Mr. Meitar Moscovitz wrote:
>
>> Either way, now I know what the proper places for things like this
>> are. Thanks!
>
> Just as a general statement, Meitar, you're asking really great
> questions that I'm sure all newcomers to the docs team are going to
> struggle with. How would you feel about making a "Documentation
> Contribution FAQ" or something like that that, which contains a list
> of the questions you asked and the answers you've gleaned from the
> list, in words that a fellow new contributors like yourself could
> understand? I'd be happy to proof-read it for you, if you'd like.

That makes sense to me. I'm sure most of the answers to such questions
already exist in many places, but in all the places that I've found
what turned out to be correct answers, they were pretty brief and hard
to interpret. For instance, here, in "Updating API documentation" http://drupal.org/node/144223
 there's a short section headlined "Code" that has two sentences in it:

> All documentation for core functions, constants, and files are
> automatically generated from the core modules in Drupal. […] To
> update these, you must submit a core patch to edit the Doxygen
> comments of the code in question.


The text "submit a core patch" is a link to the http://drupal.org/node/add/project-issue/drupal
 page, which is far from explanatory for someone like me (until
yesterday, when Steven clued me into the details). Better, IMHO, would
be a paragraph or two (tops) with appropriate links embedded in
natural text to places such as "Doxygen formatting conventions" (http://drupal.org/node/1354
) and so forth, so the reader doesn't have to reach for the search box
in a ridiculous number of browser tabs. :)

So I guess my question is, do you think there's really a need for a
FAQ, or should I just spend a little while going through some of the
child pages to "Contributing to documentation" and fleshing them out
further?

Of course, I could always do *that*, and then *also* compose a list of
all the questions I'm asking, run them by you or a mailing list
archive search to see how frequent they are, and then post brief one-
liners with appropriate links in a new "Contributing to documentation
FAQ", as well….

> You don't have to, of course, but it just seems like it'd be great
> to get these things written up somewhere so the *next* time it
> becomes "Oh, that's covered in the FAQ at <link>. See question #2." :)
>
> -Angie

I didn't have to ask to join the Drupal docs team either, now did I? ;)

Cheers,

--
-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
--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/

[Mr. Meitar Moscovitz-2]

On Jun 3, 2008, at 9:43 PM, Steven Jones wrote:

> Hi,
>
> I'd imagine writing a FAQ by yourself would be a huge undertaking,  
> instead, why don't you create an issue in the queue (documentation  
> project) and just list any questions that you can think of, others  
> can do the same and then gradually we can move them over into  
> handbook pages. If we make each question its own page then the  
> handbook theming will give us a nice list of all of them on the  
> parent page.
>
> If there were a list of 'Unanswered FAQs'  then I'd happily spend  
> ten minutes every now and then writing an answer to one and adding  
> it. If other's did the same we'd get a high quality FAQ list in no  
> time.

Done. See:

http://drupal.org/node/266439

I've assigned this ticket to myself and will monitor it for the time  
being. I'll also add some questions when I get the chance to do so,  
and then start composing such a FAQ (probably on a new Book page so  
you can all edit it as well). Will update the issue when the book page  
is created and has some interesting content to review.

Thanks,
--
-Meitar Moscovitz
Personal: http://maymay.net
Professional: http://MeitarMoscovitz.com
--
Pending work: http://drupal.org/project/issues/documentation/
List archives: http://lists.drupal.org/pipermail/documentation/