New issue
Advanced search Search tips

Issue 609361 link

Starred by 1 user
Status: WontFix
Owner: ----
Closed: May 2016
Cc:
dpranke@chromium.org
Components:
EstimatedDays: ----
NextAction: ----
OS: ----
Pri: 3
Type: Feature



Sign in to add a comment

Improve documentation in webkitpy

Project Member Reported by qyears...@chromium.org, May 5 2016 
This is a tracking bug for the (not-currently-clearly-defined) goal of improving in-code documentation in webkitpy.

There are several types of documentation that could be useful for future readers:
 - README.md files in directories to briefly describe what that directory is for if it's not obvious.
 - method docstrings for long (> 20 lines) public methods
 - docstrings to describe the purpose of modules/classes if it's not obvious

I think it might be most worth it to start looking at w3c/, since I might be looking at that in the near future with interns, and it may also be helpful to look at the largest/most-frequently-used modules in layout_tests/.

Dirk, any thoughts?

Comment 1 by dpranke@chromium.org, May 6 2016 

I wouldn't spend much, if any, time on this, except to maybe improve things opportunistically if you're working on the code for other reasons.

In particular, we tend to prefer to document things (particularly functions and methods) via good naming rather than via docstrings, so we should only add docstrings when things are particularly weird.

Comment 2 by qyears...@chromium.org, May 6 2016

Status: WontFix (was: Unconfirmed)
That makes sense -- trying to improve readability only for things I'm trying to work on for other reasons sounds good.
►

Sign in to add a comment