Closed (fixed)
Project:
Drupal core
Version:
8.0.x-dev
Component:
documentation
Priority:
Normal
Category:
Bug report
Assigned:
Unassigned
Reporter:
Created:
2 Nov 2015 at 21:38 UTC
Updated:
16 Dec 2015 at 21:04 UTC
Jump to comment: Most recent, Most recent file
Comments
Comment #2
lars toomre commentedAppears these type of documentation fixes should be classified as bug fixes.
Comment #3
imalabyaHi,
Found a few more instances of the case. Have added the patch and interdiff file.
Comment #4
imalabyaThe interdiff file got missed.
Comment #5
jhodgdonThanks!
Comment #6
lars toomre commentedThanks @malavya for rolling a patch with additional {@inheritdoc} changes. Unfortunately the three changes you added are subtly wrong. Your additions caught the @inheritDoc errors (with a capital 'D'). The proper string is '{@inheritdoc}' (with a lower case 'd'). Hence I am setting back to 'Needs work.'
Checking the core code base, I see that there are approximately ten additional files that need to be changed from '{@inheritDoc}' to the documentation standard of '{@inheritdoc}'. I am unsure of how many files we should include in a simple documentation patch like this before it becomes too big or disruptive. That is why I was targeting about ten files in the initial patch. Perhaps one of the core committers can give some feedback?
Comment #7
lars toomre commented@jodgdon: If you see this comment, perhaps you can also advise if '@inheritdoc' is permissible in our javascript documentation standards. Both of the patches in this issue only address *.php files. There are approximately a dozen *.js files that might need to be addressed as well.
Comment #8
jhodgdonThanks Lars, you are right. Let's get all the inheritdoc problems together.
Comment #9
jhodgdonRegarding #7, the person to ask about that would be _nod, the JavaScript maintainer. I believe there is a standards page for JavaScript docs too. Not my expertise, sorry!
Comment #11
lars toomre commentedHere is an updated patch taking into account both comments #6 and #7. The attached interdiff is against the original patch since the changes in #3 were slightly wrong (capital 'D' vis-a-vis lower case 'd'). Thanks for your help with this issue @malavya.
Comment #12
imalabyaI checked into the documentation for the @inheritdoc for JavaScript
https://developers.google.com/closure/compiler/docs/js-for-compiler?hl=en
The documentation shows the example as:
Currently we have:
@jhodgdon, @_nod what do you suggest? should we be changing it as shown in the documentation?
Comment #13
nod_I'd rather leave is alone. we're not following google code style. Also keeping the current header makes things consistent, which is nice.
Comment #14
jhodgdonThanks for the patch! Sorry for delay in review -- I've been on vacation.
So the patch in #11 seems fine to me, and we should not be changing JS files, so let's just get this in.
Comment #15
jhodgdonThanks again! Committed to both 8.x branches.