Doc updates for Plug & LiveView

[vincentvanbush]

Pull Request

Description

Contains significant documentation improvements for clarity and completeness in both LiveView and controller authorization, as well as configuring action behaviour.

Also piggybacks a change in the way Permit.Phoenix.Plug is used from within Permit.Phoenix.Controller - it's now used directly as a plug module. Moreover, you can no longer use this plug directly from a controller and this is reflected in raising an error when it is attempted - and the moduledoc has been removed in favour of a better documentation in Permit.Phoenix.Controller.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Performance improvement
• Code refactoring
• Test improvements
• CI/CD improvements

Related Issues

Fixes #36

Changes Made

• Documentation updates
• Permit.Phoenix.Plug used as plug module

Testing

Test suite passing without modification.

Test Environment

• Elixir version: 1.19.3
• OTP version: 28
• Phoenix version: 1.8.1
• LiveView version: 1.1.17
• Database (if applicable): PostgreSQL 15

Test Cases

• All existing tests pass
• New tests added for new functionality at appropriate levels
• Manual testing performed
• Controller integration tests (if applicable)
• LiveView integration tests (if applicable)
• Router integration tests (if applicable)

Test Commands Run

# List the commands you ran to test
mix test
MIX_ENV=test mix credo
MIX_ENV=test mix dialyzer

Documentation

• Updated README.md (if applicable)
• Updated documentation comments (with examples for new features)
• Updated CHANGELOG.md (if applicable)
• Updated controller/LiveView usage examples (if applicable)

Code Quality

• Code follows the existing style conventions
• Self-review of the code has been performed
• Code has been commented, particularly in hard-to-understand areas
• No new linting warnings introduced
• No new Dialyzer warnings introduced
• Follows Phoenix and LiveView conventions

Phoenix/LiveView Specific

• Controller changes properly handle conn state
• LiveView changes properly handle socket state
• Router integration works correctly
• Error handling follows Phoenix patterns
• Authorization flows work as expected

Backward Compatibility

• This change is backward compatible
• This change includes breaking changes (please describe below)
• Migration guide provided for breaking changes

Breaking Changes

Performance Impact

• No performance impact
• Performance improvement
• Potential performance regression (please describe)

Performance Notes

Security Considerations

• No security impact
• Security improvement
• Potential security impact (please describe)

Additional Notes

Screenshots/Examples

Checklist

• I have read the Contributing Guidelines
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published

Reviewer Notes

---

[itamm15]

❤️