Opened 4 years ago

Closed 4 years ago

#22663 closed Uncategorized (wontfix)

Documentation of "for internal use only" code

Reported by: Daniele Procida Owned by: nobody
Component: Documentation Version: master
Severity: Normal Keywords:
Cc: Triage Stage: Unreviewed
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

There is documentation in 1.6 and in dev for code that is not really intended for public consumption, even though some of it is reasonably well-known and used.

Documentation in 1.6:

Documentation which will be there in the 1.7 release unless removed:

https://code.djangoproject.com/ticket/21139 has a draft patch that has remained unmerged because of doubts about the advisibility of documenting code in django.utils.functional that works, but isn't intended for public use.

This patch extends the documentation, but also adds a warning about using it: https://github.com/django/django/pull/1777/files#diff-fae9599a3895c42eca4588a393b61952R426

We have various options including:

  • strip all references to it from the documentation on the basis that it should not be documented
  • continue documenting it, but make sure the warnings are clear, and commit to making the code more suitable for general use

I much prefer the latter option, and dislike the idea of using the absence of documentation as a strategy.

However, if these references really should not make it into 1.7 then they should be removed.

Change History (5)

comment:1 Changed 4 years ago by Tim Graham

I don't have an opinion on the functions in question, but just wanted to chime in on the purpose of Django's documentation according to... itself. From API Stability: "All the public APIs (everything in this documentation) will not be moved or renamed without providing backwards-compatible aliases."

I think you would agree that not everything in django.utils should be documented. Is your main concern that some functions in a given file are documented, but not others? I think we should be free to add things in django.utils where they make sense without worrying about them being robust, stable APIs. Keep the main thing (a web development framework), the main thing.

comment:2 Changed 4 years ago by Daniele Procida

One issue we have is: if some of the things that should not be document are documented, what should we do about the existing documentation, in 1.6 and 1.7? Should it be removed?

comment:3 Changed 4 years ago by Tim Graham

Sure, better to remove it sooner than later.

comment:4 Changed 4 years ago by Tim Graham

from Simon:

IMO I don't think we should document all objects present in the django.utils.functionnal but cached_property is definitely a good candidate for being part of the public API.

It's a common optimization pattern that newcomers might find hard to implement correctly. Plus it don't think it would be a great burden to maintain.

comment:5 Changed 4 years ago by Tim Graham

Resolution: wontfix
Status: newclosed

allow_lazy() has been documented since 1.4 [62bb4b8c] and I think cached_property() is fine to keep. It's gotten multiple +1s on this PR.

Note: See TracTickets for help on using tickets.
Back to Top