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.

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

Lars Toomre’s picture

Status: Active » Needs review
FileSize
79.49 KB

This 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.

dawehner’s picture

Issue tags: +VDC

Adding tags

xjm’s picture

Status: Needs review » Postponed

Awesome, 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.

Lars Toomre’s picture

Status: Postponed » Needs review
FileSize
23.55 KB

I 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.

Lars Toomre’s picture

Status: Needs review » Postponed

Putting back to postponed. Patches in #1 and #4 are different and both apply as of the time of this post.

xjm’s picture

Project: Views (for Drupal 7) » Drupal core
Version: 8.x-3.x-dev » 8.x-dev
Component: Documentation » documentation
Lars Toomre’s picture

@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.

xjm’s picture

Thanks 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.

Lars Toomre’s picture

Thanks for the explanation @xjm. Perhaps we should use this issue as a META issue for what its title states?

xjm’s picture

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

Lars Toomre’s picture

Component: documentation » views.module

@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.

xjm’s picture

Sure, I'll try to do that when I have some time.

Version: 8.0.x-dev » 8.1.x-dev

Drupal 8.0.6 was released on April 6 and is the final bugfix release for the Drupal 8.0.x series. Drupal 8.0.x will not receive any further development aside from security fixes. Drupal 8.1.0-rc1 is now available and sites should prepare to update to 8.1.0.

Bug reports should be targeted against the 8.1.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.2.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.1.x-dev » 8.2.x-dev

Drupal 8.1.9 was released on September 7 and is the final bugfix release for the Drupal 8.1.x series. Drupal 8.1.x will not receive any further development aside from security fixes. Drupal 8.2.0-rc1 is now available and sites should prepare to upgrade to 8.2.0.

Bug reports should be targeted against the 8.2.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.3.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.2.x-dev » 8.3.x-dev

Drupal 8.2.6 was released on February 1, 2017 and is the final full bugfix release for the Drupal 8.2.x series. Drupal 8.2.x will not receive any further development aside from critical and security fixes. Sites should prepare to update to 8.3.0 on April 5, 2017. (Drupal 8.3.0-alpha1 is available for testing.)

Bug reports should be targeted against the 8.3.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.4.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.3.x-dev » 8.4.x-dev

Drupal 8.3.6 was released on August 2, 2017 and is the final full bugfix release for the Drupal 8.3.x series. Drupal 8.3.x will not receive any further development aside from critical and security fixes. Sites should prepare to update to 8.4.0 on October 4, 2017. (Drupal 8.4.0-alpha1 is available for testing.)

Bug reports should be targeted against the 8.4.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.5.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.4.x-dev » 8.5.x-dev

Drupal 8.4.4 was released on January 3, 2018 and is the final full bugfix release for the Drupal 8.4.x series. Drupal 8.4.x will not receive any further development aside from critical and security fixes. Sites should prepare to update to 8.5.0 on March 7, 2018. (Drupal 8.5.0-alpha1 is available for testing.)

Bug reports should be targeted against the 8.5.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.6.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.5.x-dev » 8.6.x-dev

Drupal 8.5.6 was released on August 1, 2018 and is the final bugfix release for the Drupal 8.5.x series. Drupal 8.5.x will not receive any further development aside from security fixes. Sites should prepare to update to 8.6.0 on September 5, 2018. (Drupal 8.6.0-rc1 is available for testing.)

Bug reports should be targeted against the 8.6.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.7.x-dev branch. For more information see the Drupal 8 minor version schedule and the Allowed changes during the Drupal 8 release cycle.

Version: 8.6.x-dev » 8.8.x-dev

Drupal 8.6.x will not receive any further development aside from security fixes. Bug reports should be targeted against the 8.8.x-dev branch from now on, and new development or disruptive changes should be targeted against the 8.9.x-dev branch. For more information see the Drupal 8 and 9 minor version schedule and the Allowed changes during the Drupal 8 and 9 release cycles.

andypost’s picture

Version: 8.8.x-dev » 9.1.x-dev
Issue summary: View changes
Status: Postponed » Active
Parent issue: » #2052421: [META] Rename Views properties to core standards
Related issues: +#3034944: Fix docblocks in Views filter plugins

probably the issue is outdated

Version: 9.1.x-dev » 9.2.x-dev

Drupal 9.1.0-alpha1 will be released the week of October 19, 2020, which means new developments and disruptive changes should now be targeted for the 9.2.x-dev branch. For more information see the Drupal 9 minor version schedule and the Allowed changes during the Drupal 9 release cycle.

Version: 9.2.x-dev » 9.3.x-dev

Drupal 9.2.0-alpha1 will be released the week of May 3, 2021, which means new developments and disruptive changes should now be targeted for the 9.3.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.3.x-dev » 9.4.x-dev

Drupal 9.3.0-rc1 was released on November 26, 2021, which means new developments and disruptive changes should now be targeted for the 9.4.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.4.x-dev » 9.5.x-dev

Drupal 9.4.0-alpha1 was released on May 6, 2022, which means new developments and disruptive changes should now be targeted for the 9.5.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

Version: 9.5.x-dev » 10.1.x-dev

Drupal 9.5.0-beta2 and Drupal 10.0.0-beta2 were released on September 29, 2022, which means new developments and disruptive changes should now be targeted for the 10.1.x-dev branch. For more information see the Drupal core minor version schedule and the Allowed changes during the Drupal core release cycle.

quietone’s picture

Status: Active » Closed (outdated)

Changes 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.