Page MenuHomePhabricator

Update documentation of code across Reading-Web-maintained extensions
Closed, DeclinedPublic

Description

Problem:

There are several undocumented methods, parameters, return values, etc. within our extensions, as well as just poorly documented ones (ApiMobileView::execute, for example). A clean sweep is probably overdue. This bullet point alone could translate to an epic with subtasks for checking/fixing documentation for every feature.

This task is obviously too large and should probably become an epic, but I'm unsure of the best way to split it up. Let's figure that out during a grooming meeting or async.

Event Timeline

Restricted Application added a subscriber: Aklapper. · View Herald TranscriptAug 18 2016, 4:46 PM
jhobs triaged this task as Normal priority.Aug 18 2016, 5:18 PM
jhobs moved this task from Incoming to Triaged but Future on the Readers-Web-Backlog board.
Jdlrobson added a subscriber: Jdlrobson.

This needs breaking down if we do want to work on it. It's not Triaged but future.

This is basically a card which says "document all our existing code". Documentation can always be improved so this card is unlikely to ever be resolved.

Would it make sense to organise a documentation day where we all sit down and do nothing but improve our existing documentation?
@bmansurov @phuedx @pmiazga @Jhernandez is that something you'd be interested in?

Jdlrobson closed this task as Declined.May 1 2017, 8:41 PM

I'm going to argue that increasing code coverage will help this. When writing tests we will also document methods better - T151340. Documentation is something we should be thinking about and improving all the time. If someone has ideas for a specific piece of documentation that needs improving please open a specific task with the details.

Documentation day sounds good. In general, we should put more focus on documenting code, every time we find undocumented function we should add comments. That's no brainer.