[wp-meta] [Making WordPress.org] #447: Link to actual source from reference pages

[Making WordPress.org]

#447: Link to actual source from reference pages
---------------------------+-------------------------------------
  Reporter:  DrewAPicture  |      Owner:
      Type:  enhancement   |     Status:  new
  Priority:  normal        |  Component:  developer.wordpress.org
Resolution:                |   Keywords:  has-patch
---------------------------+-------------------------------------

Comment (by coffee2code):

 Replying to [comment:4 DrewAPicture]:
 > Replying to [comment:3 coffee2code]:
 > > I prefer the "Source:" link to be unchanged (the source file name
 linking to the source file archive), and that we add a "View source" link
 somewhere. Verbiage and location could do with additional input. @sams?
 @siobhan? If the consensus if for what @DrewAPicture proposed, I'm fine
 with that.
 >
 > Hmm. I like using "View source" for the source browser link but disagree
 with using "Source" for the "source term". I think it's misleading. What
 about "Source file" and "View source" or similar?
 >

 I'm cool with that. However it is labeled, I feel the linked filename
 should link to the term archive and not the source for the function.

 > > ----
 > > Nitpicks:
 > > * The core.trac link should point to the tagged release and not to
 trunk, since trunk will always be in flux, likely causing line numbers to
 not sync up.
 >
 > It was my understanding from multiple conversations that we'd be parsing
 trunk on a regular basis -- half the reason for parsing docs in the first
 place. Is that not the case?

 Hmm, that's not my understanding. Personally I don't feel parsing trunk is
 worthwhile due to its in-flux nature. Basically if doing so you're
 documenting code that hasn't been released yet and isn't guaranteed to be
 released. If we're presenting a single definitive documentation source,
 the latest release should be it, not trunk.

 Why do you feel that parsing trunk is "half the reason for parsing docs in
 the first place"? Is not documenting the latest release sufficient? It's
 what most people should be using. Like I said, until a release is made,
 anything in trunk could be yanked/changed before release.

 I'm aware a discussion on
 [https://meta.trac.wordpress.org/timeline?from=2014-02-20T04%3A09%3A34-06%3A00&precision=second
 another ticket, #331] touched on this and spawned a brief discussion. I
 agree with @GaryJ and @Rarst there. Trunk isn't stable and shouldn't be
 the definitive documentation source. I see your point that it'd be nice to
 incorporate doc updates in core as they happen, but I'm not aware of an
 effort to differentiate between update-improvements-of-existing-docs and
 docs-for-newly-introduced-functions. There isn't a current provision to
 recognize stuff later than a given version so that it could be ignored on
 the site.

 After recent efforts, a lot of what exists has been better documented. And
 given our fairly quick release cycle nowadays, I don't see the harm in
 waiting until the next release to have updated inline docs becoming
 available.

 Bear in mind documentation isn't black and white between doc-updates-to-
 existing-functions and docs-for-new-functions, i.e. using `@since` as some
 sort of flag. Existing functions could have existing arguments changed,
 deprecated, or new arguments added, which would not be reflected in the
 function's `@since`.

 Maybe this aspect is worth a ticket of its own so it can be debated since
 it has arisen as tangential discussions for at least two tickets.

--
Ticket URL: <https://meta.trac.wordpress.org/ticket/447#comment:5>
Making WordPress.org <https://meta.trac.wordpress.org/>
Making WordPress.org