Support for Drupal 7 is ending on 5 January 2025—it’s time to migrate to Drupal 10! Learn about the many benefits of Drupal 10 and find migration tools in our resource center.We need comprehensive documentation.
We already have fairly good inline documentation, but we should look it over to make sure it is all good.
There are a number of things to do for documentation:
* README.txt for all modules (Do we keep API and hook documents in another file?)
* Advanced Help (what should go here and in README's?)
* Documentation page on d.o (this can be a growing document)
Comments
Comment #1
zzolo CreditAttribution: zzolo commentedWe should use an openlayers.api.php to create doxygen documentation. Why?
* This is how core does it.
* It can be easily parsed for outputting to other formats.
* This is probably the most friendliest format for potential developers.
Comment #2
zzolo CreditAttribution: zzolo commentedInline documentation and Doxygen format.
There was the following in the openlayers hook implementation in the openlayers.module file:
This is bad syntax and unnecessary. See: http://drupal.org/node/1354#contrib
We only want to use groups to:
* Group the module files together
* Group any specific functions together, (ie the API functions together)
The main goal of the Doxygen formatting is to make it a lot easier to browse when parsed, so its important to have simple and sane groups.
I only write this to help, though I know it can come off as as obsessive compulsive.
Comment #3
phayes CreditAttribution: phayes commentedSounds good. I didn't really understand the purpose of @ingroup. Please do change it.
Comment #4
zzolo CreditAttribution: zzolo commentedIt is a real simple designation to put something in a group. It's pretty arbitrary. One does have to define the group with @defgroup first. The only two reasons I was thinking of using it was:
* to group our files together since we have multiple modules in this project, and
* to group the API calls together since these are the functions that other developers will need to reference easily.
Comment #5
zzolo CreditAttribution: zzolo commentedJust to show in a visual way how helpful inline documentation is, I have put up a snapshot of the module on my API site:
* http://api.zzolo.org/api/file/drupal-6-contrib/openlayers/openlayers.mod...
* Then in specific functions, you can see the related topics section: http://api.zzolo.org/api/function/openlayers_merge_maps/drupal-6
* Specific API group (@ingroup): http://api.zzolo.org/api/group/openlayers_api/drupal-6
I am just noticing that @ingroup for files does not seem to be support in the API module. Well, it is still good practice, and we could use a more robust Doxygn parser to create documentation as well.
Comment #6
zzolo CreditAttribution: zzolo commentedChanging this to Inline documentation. This includes the files in the /docs folder. The main thing at the moment that needs addressing is the MAP_ARRAY.txt file. I think we can just push this to the Advnaced help since it is a large amount of documentation and we don't want to duplicate that effort.
Sepearated out documentation tasks:
* #555976: Advanced Help Documentation for 1.0
* #555978: Handbook Page Documentation for 1.0
Comment #7
zzolo CreditAttribution: zzolo commentedComment #8
zzolo CreditAttribution: zzolo commentedI have decided to move this documentation to the Advanced Help integration. It seemed redundant to put things in both places, and annoying to spit it up. So, I think our inline documentation for the 1.x branch is as complete as it will get. Please see #555976: Advanced Help Documentation for 1.0 for the more integrated documentation that comes with the module.