Early Bird Registration for DrupalCon Portland 2024 is open! Register by 23:59 PST on 31 March 2024, to get $100 off your ticket.
Doxygen and comment formatting conventions for D8 are summarized on http://drupal.org/node/1354. We need to move toward (and ideally conform with) these standards if views is to be accepted as a core module.
This issue is where a series of documentation-oriented patches will be submitted.
Comment | File | Size | Author |
---|---|---|---|
#4 | views_ui.module-1793510-4.patch | 23.55 KB | Lars Toomre |
#1 | admin.inc-file-1793510-1.patch | 79.49 KB | Lars Toomre |
Comments
Comment #1
Lars Toomre CreditAttribution: Lars Toomre commentedThis first patch was inspired by patch #1788232: Move UI properties from ViewExecutable to a new ViewUI class. In that patch, ViewUI type hinting was added to various function definitions.
The original intent here was to add similar type hinting to the appropriate @param directives. However, when starting to do so in admin.inc file, I found that some docblocks and many @param/@return directives were missing. The attached patch is a major first pass at bringing this one file into compliance with http://drupal.org/node/1354.
Where I was uncertain about a variable type and/or description, I have left '???' to be addressed by someone more familiar with those functions. Finally, I do not have a testing environment so this patch is untested.
Comment #2
dawehnerAdding tags
Comment #3
xjmAwesome, thanks @Lars Toomre. This looks like a great start to improving Views' documentation, which is going to be a really important step for us before release.
I'm going to postpone this issue for now, because this is going to be time-intensive to review and refine, and VDC is on a really tight schedule for the next ten weeks especially, so the team can't give this patch the attention it deserves yet. See our status report and roadmap for what initiative tasks are targeted during each phase of the release cycle. We'll use this patch as a starting point for improving Views' documentation during code freeze.
I should point out that I'm only postponing documentation cleanups that are out of scope for our current issues. Other patches going into Views 8.x-3.x should follow D8 core's docs standards and the core documentation gate, and it'd be great to have your help polishing and rerolling those patches.
Comment #4
Lars Toomre CreditAttribution: Lars Toomre commentedI was working on the rest of the @param/@return type hint directives in #1788232: Move UI properties from ViewExecutable to a new ViewUI class before this was changed to postponed. The attached patch cleans up three more files, but is mostly concentrated on views_ui.module.
As I do not have a testing environment, I am setting this back to needs review for a test run and will set it to postponed afterwards.
Comment #5
Lars Toomre CreditAttribution: Lars Toomre commentedPutting back to postponed. Patches in #1 and #4 are different and both apply as of the time of this post.
Comment #6
xjmComment #7
Lars Toomre CreditAttribution: Lars Toomre commented@xjm Thanks for moving this issue into the appropriate core queue.
When is it appropriate, please take a closer at the documentation and dive further into, for instance, what eventually will be the near final D8 view.api.php? Should one file separate issues now to make that file even better (noting the many improvements one (primarily @xjm) already have made simply to get the documentation to where it is presently)?
Also, please understand in advance, my question above is in no way any criticism of the VDC team's efforts.
All of you on the VDC team are to be lauded like the Greek gods for an effort that I thought never would come until D1x+. Thanks in advance for your amazing efforts .
I will simply leave my key comment on this issue as "Hugs!! and no doubt time away from families and other loved ones. Thank you again (which I wish many more in the potential beneficiaries of D8 would state) for your long hours for helping make views be part of core D8.
Comment #8
xjmThanks so much @Lars Toomre!
I summed up our plan here:
#1805996-60: [META] Views in Drupal Core
The idea is to start some cleanups and documentation improvements throughout the Views codebase after the critical Dec. 1 feature freeze deadline (38 days from now). Then, during code freeze (which starts April 1), we will focus exclusively on the upgrade path and QA: making the documentation really shine, adding test coverage and fixing bugs, and improving performance.
In the interim, we'll want to improve the documentation for all new patches, and we may be adding additional detailed documentation for complex and critical topics like the hook execution order,
hook_views_data()
, the plugin types, and annotations. Edit: We also might not write those detailed docs yet, since it's possible yet that we may completely change some things.Comment #9
Lars Toomre CreditAttribution: Lars Toomre commentedThanks for the explanation @xjm. Perhaps we should use this issue as a META issue for what its title states?
Comment #10
xjmIn general I prefer that meta issues have no patches against them, to avoid confusion, but we'll definitely link it here at a minimum once we start allowing standards cleanups. Thanks!
Comment #11
Lars Toomre CreditAttribution: Lars Toomre commented@xjm re #10: Could you create an issue about making Views conform to D8 documentation standards?
Clearly from the VDC road-map, this item is not expected to be completed until after December 1 2012.
However, it would be very useful to have a queue issue for what eventually needs to be addressed/corrected. Thanks in advance.
Comment #12
xjmSure, I'll try to do that when I have some time.
Comment #20
andypostprobably the issue is outdated
Comment #26
quietone CreditAttribution: quietone at PreviousNext commentedChanges to documentation that are to meet coding standards are now done by sniff. The meta #2571965: [meta] Fix PHP coding standards in core explains the history of this decision in the Issue Summary. Other documentation improvements are made when someone discovers a discrepancy. So, there is no need to keep an issue to over see documentation changes to one module.
I am closing this as outdated, because of the change of approach.