Issue Summary
currently, api.module requires a @mainpage somewhere in the code to show *any* documentation. this has (at least) 2 drawbacks:
1) authors of contributed modules and themes wanting to use api.module to document *only their module/theme* have to put a @mainpage somewhere in their module/theme to see documentation. problem: running api.module on the whole contributions repository finds many @mainpage commands, and puts a wrong one on the repositorys main page (see http://drupal.kollm.org/doxygen/_contrib/drupal-contrib-phpdoc/ ). not so nice.
2) it is incompatible with Doxygen. in Doxygen, @mainpage is used to /customize/ the index page, not to /define/ it. if there is no @mainpage, Doxygen just generates a default (empty) one. in any case, the documentation is accessible.
please remove this requirement. thanks!
Comments
#1
Those who want to use the API module to document their own modules should check out the developer documentation from CVS. They should then use @defgroup or @file to provide pages for their modules. They can point the front pages of their sites to the @defgroup or @file pages instead of using the main API page.
P.S. This is part of the Drupal coding standards. I would suggest posting a bug report to each module that violates the rules.
#2
The Drupal contrib Doxygen coding standards were written by me in an attempt to avoid these kind of problems. It doesn't work out, though. The root cause is that api.module violates Doxygen conventions re: @mainpage, so this should be fixed. Thanks!
#3
H
I document the print module in my personal homepage using the API module.. I'd like not to define '@mainpage' in the module, but without it the API module doesn't generate any documentation. Checking out the entire developer docs is overkill and not really the 'good' solution.
I would agree that it would be much better if @mainpage is used to customize the page and not to define it.. I'll try to take a look at it.
#4
The developer docs are very compact, and they provide structure for all Drupal documentation. You are more likely to create incompatible documentation if you don't include them.
#5
This has no incompatibilities..
#6
How should I be using @addtogroup hooks in mymodule.api.php?
Should I be also using @defgroup mymoudle?
#7
Yes. @defgroup will contain the documentation for your group.
#8
All documentation is accessible, the /api page just looks super lame. Another page, like the function list, can be linked to. A good default should be designed and implemented. Ideally something we are proud enough to use on the api.drupal.org home instead of @mainpage.
#9
#10
This patch contains a simple change to the api.module that uses the first group documented as the default API reference page if no mainpage is defined..
With this, modules following the Drupal coding standards will have 'decent' default pages when running the API module for documenting those modules exclusively and the mainpage functionality is left intact for use by the main Drupal contrib page.
At least for me, it allows me to get rid of the api/index.php file (and the @mainpage) in the print module and still be able to run API for documenting those modules..
#11
Slightly modified the patch in #10.
The check for object_name equaling the branch name doesn't make sense and only works if the defined group name is the same as the branch name, so I simplified the condition to return the group documentation for the first group defined in the branch.
João
#12
This seems a bit arbitrary, the first group could be anything. Fixing #218306: Allow multiple, partitioned paths to be indexed would remove the conflict, since each project could have its own mainpage. Something still needs to be done in absence of any mainpage.
#13
#14
Would it be acceptable to show the list of defined groups? And in case there's only one, show that group's page directly?
#15
Why can't you assume if I have no groups, then they're all one group. Consider it the 'ungrouped' group - I dunno. Seems pointless to go through everything just to add one dummy group.
#16
Well, the dummy group is part of Drupal's coding standards...
#17
That's a recommendation from an anonymous author to do something that doesn't make sense to me :/. Plus I shouldn't have to follow the Drupal coding standards to use this module, I don't necessarily have to use it for a Drupal related project, do I?
#18
I agree, those group-related coding standards should be thought of as guidelines. They make ax's site work a bit better, but I'm not sure if the site is practical at all. I would be interested if he found a way to get the right version of everything considering all of the branches we use, http://drupal.org/node/97084.
With the current PHP parser in api module, following the coding standards will otherwise be rewarded. For example, imprecise indentation can confuse the parser. That is why it is being replaced in #300031: Rework PHP parser.
In the future, more Drupalisms, like modules, hooks, and themeable functions should be built into API module. My motivation is to make an excellent API documentation for Drupal. I don't plan on doing anything that hurts other projects, but you should pay attention and look for anything relevant. I don't know what is good for non-Drupal codebases since I am not familiar with them.
For the default index page. A simple list of groups and links to the list of files, globals, constants, etc is a decent start. I would like to see much more in the future. Ideas for other things that could be added:
* New functions/files/etc in this version
* Changed functions in this version
* Most referenced functions
* Recently updated items
Anything beyond the basics needs to be thought out and go through a design process, we need to know something useful to end users is being done.
#19
Something like this?
I left the warning message at the end, unchanged. You may want to remove it or simplify it..
#20
Looking better. I think most of this should be in a .tpl.php file since there is markup. The h3 tags should be outside the l()s, so $options can be removed, and that is valid HTML.
The br and small should be removed, a class added to the p tag, and CSS used for margin and size.
#21
As suggested in #20, I moved the HTML into a template, and used some CSS for the size and spacing around the mainpage warning.
Crossing my fingers for this to get in version 1.2 final.
#22
Committed with some minor style changes.
#23
Automatically closed -- issue fixed for 2 weeks with no activity.