[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 DrewAPicture):

 Replying to [comment:5 coffee2code]:
 > Replying to [comment:4 DrewAPicture]:
 > > > ----
 > > > 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.
 >
 > <snip>
 >
 > 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.
 >

 In the absence of parsing different versions of !WordPress separately,
 e.g. 3.8, 3.9, 4.0, parsing trunk for the overall reference is the
 preferred alternative. Look at the Drupal API docs. They're parsing and
 disseminating in-progress docs for Drupal 8 even while Drupal 7.x is the
 stable release.

 Honestly, parsing by version would be ideal -- meaning we'd parse core
 upon the x.x release and save it, upadting in the event of a point
 release. Followed by independently parsing trunk as the new x.x+1 release,
 clearly marking new APIs as experimental and every other page as likely in
 flux.
 >
 > <snip>
 >
 > 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`.

 See my point above. I think developers are quick enough to understand that
 the x.x+1 docs they're viewing are for a future release, not to be
 confused with docs for the current stable.

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

 Probably.

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