Re: [Django] #12856: Decide on public API/documentation for form.BoundField attributes
Django
-------------------------------------+-------------------------------------
Reporter: mnbayazit | Owner: nobody
Type: New | Status: new
feature | Component: Forms
Milestone: | Severity: Normal
Version: SVN | Keywords: boundfield required
Resolution: | is_hidden auto_id
Triage Stage: Accepted | Has patch: 1
Needs documentation: 1 | Needs tests: 0
Patch needs improvement: 1 | Easy pickings: 0
-------------------------------------+-------------------------------------
Changes (by aaugustin):
* easy: => 0
Comment:
#16125 was a duplicate. The tickets suggests some fields that should be
documented in priority.
--
Ticket URL: <https://code.djangoproject.com/ticket/12856#comment:9>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
-------------------------------------+-------------------------------------
Reporter: mnbayazit | Owner: nobody
Cleanup/optimization | Component: Forms
Version: SVN | Keywords: boundfield required
Resolution: | is_hidden auto_id
Triage Stage: Accepted | Has patch: 1
Needs documentation: 1 | Needs tests: 0
Patch needs improvement: 1 | Easy pickings: 0
-------------------------------------+-------------------------------------
Changes (by jsdalton):
* cc: jim.dalton@… (added)
* ui_ux: => 0
* type: New feature => Cleanup/optimization
Comment:
I think a more appropriate place to extend the documentation on
`BoundField` is in the Forms API document:
https://docs.djangoproject.com/en/dev/ref/forms/api/#more-granular-output
. That's not to say we should not extend the Working With Forms docs a
bit, but if I'm a developer and I want to find out more about what
`BoundField` has to offer, Forms API is likely the place I will begin.
In an effort to help push this forward, here is what we have documented
now:
* `class ``BoundField```
* `BoundField.errors`
* `BoundField.css_classes()`
* `BoundField.value()`
Then in Working With Forms the following are documented (albeit as
template output, not explicitly as methods of BoundField).
* `BoundField.label`
* `BoundField.label_tag`
* `BoundField.html_name`
* `BoundField.help_text`
* `BoundField.errors`
* `BoundField.is_hidden`
Here is what is missing (i.e. not covered by either of the above).
* `BoundField.field`
* `BoundField.html_initial_name`
* `BoundField.html_initial_id`
* `BoundField.as_widget()`
* `BoundField.as_text()`
* `BoundField.as_textarea()`
* `BoundField.as_hidden()`
* `BoundField.data`
* `BoundField.auto_id`
* `BoundField.id_for_label`
My two cents:
* It seems like all of the attributes described in working with forms
deserve a mention in Forms API? It strikes me as odd to read the API docs
on a class with no mention of the some of the most important attributes on
it.
* `BoundField.id_for_label` is almost a no brainer for me. If you're doing
granular output, e.g. writing your own label tag, then getting the id is
necessary.
* I've used `BoundField.auto_id`in the past when (I now realize) I should
have been using id_for_label. It might be worth noting that id_for_label
is recommended for template output over auto_id?
* I have no opinion on documenting the `as_*()` functions. Seems
unnecessary to me, they are mostly internal.
* `required` is documented on
https://docs.djangoproject.com/en/dev/ref/forms/fields/ , which is a
different beast IMO. I'd argue the documentation for those should stay
there. Maybe we could put a note with a link to the fields doc?
* Petr's patch adding the field to BoundField might be a good one, but I'm
not sure it belongs here? It strikes me as a separate issue. This seems to
primarily be a ticket related to improving the documentation of existing
fields.
--
Ticket URL: <https://code.djangoproject.com/ticket/12856#comment:10>
Django
-------------------------------------+-------------------------------------
Reporter: mnbayazit | Owner: nobody
Type: | Status: new
Component: Documentation | Resolution:
Severity: Normal | Triage Stage: Accepted
Keywords: boundfield required | Needs documentation: 1
is_hidden auto_id | Patch needs improvement: 1
Has patch: 1 | UI/UX: 0
Needs tests: 0 |
Easy pickings: 0 |
-------------------------------------+-------------------------------------
Changes (by timo):
* component: Forms => Documentation
--
Ticket URL: <https://code.djangoproject.com/ticket/12856#comment:11>
Django
-------------------------------------+-------------------------------------
Type: | Status: assigned
Cleanup/optimization |
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: boundfield required | Triage Stage: Accepted
is_hidden auto_id |
Has patch: 0 | Needs documentation: 1
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
* owner: nobody => MoritzS
* needs_better_patch: 1 => 0
* has_patch: 1 => 0
* status: new => assigned
--
Ticket URL: <https://code.djangoproject.com/ticket/12856#comment:12>
Django
-------------------------------------+-------------------------------------
Reporter: mnbayazit | Owner: MoritzS
Type: | Status: assigned
Cleanup/optimization |
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: boundfield required | Triage Stage: Accepted
is_hidden auto_id |
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Changes (by MoritzS):
* needs_docs: 1 => 0
* has_patch: 0 => 1
Comment:
Added PR: https://github.com/django/django/pull/5123
--
Ticket URL: <https://code.djangoproject.com/ticket/12856#comment:13>
Django
-------------------------------------+-------------------------------------
Reporter: mnbayazit | Owner: MoritzS
Type: | Status: assigned
Cleanup/optimization |
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: boundfield required | Triage Stage: Accepted
is_hidden auto_id |
Has patch: 1 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
* needs_better_patch: 0 => 1
--
Ticket URL: <https://code.djangoproject.com/ticket/12856#comment:14>
Django
-------------------------------------+-------------------------------------
Reporter: mnbayazit | Owner: MoritzS
Type: | Status: assigned
Cleanup/optimization |
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: boundfield required | Triage Stage: Accepted
is_hidden auto_id |
Has patch: 1 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
* needs_better_patch: 1 => 0
Comment:
Updated PR
--
Ticket URL: <https://code.djangoproject.com/ticket/12856#comment:15>
Django
-------------------------------------+-------------------------------------
Reporter: mnbayazit | Owner: MoritzS
Type: | Status: assigned
Cleanup/optimization |
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: boundfield required | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
* keywords: boundfield required is_hidden auto_id => boundfield required
is_hidden auto_id 1.9
* needs_better_patch: 0 => 1
Comment:
There's one outstanding question related to documenting a method that may
not need to be depending on the results of template widget rendering, but
otherwise this is in good shape for 1.9.
--
Ticket URL: <https://code.djangoproject.com/ticket/12856#comment:16>
Django
-------------------------------------+-------------------------------------
Reporter: mnbayazit | Owner: MoritzS
Cleanup/optimization |
Component: Documentation | Version: master
Keywords: boundfield required | Triage Stage: Accepted
is_hidden auto_id 1.9 |
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
* status: assigned => closed
* resolution: => fixed
Comment:
In [changeset:"2f53d342f1ce2fb36cddbd90e24c4fda86389c27" 2f53d34]:
{{{
#!CommitTicketReference repository=""
revision="2f53d342f1ce2fb36cddbd90e24c4fda86389c27"
Fixed #12856 -- Documented BoundField API.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/12856#comment:17>