Page MenuHomePhabricator

Write style guide for function inline commenting
Closed, ResolvedPublic

Description

Assigning to Zak (hope he doesn't mind).

Some places we're using

  • @param $action \type{\string}

others it's

  • @param $action string

Version: unspecified
Severity: enhancement

Details

Reference
bz25408

Event Timeline

bzimport raised the priority of this task from to Medium.Nov 21 2014, 11:11 PM
bzimport set Reference to bz25408.
bzimport added a subscriber: Unknown Object (MLST).

I thought the [[mw:Manual:Coding_conventions]] already covered Doxygen syntax? If not, that'd be where it should go :)

http://www.mediawiki.org/wiki/Manual:Coding_conventions

Yeah, it's there, but it should be more verbose, list some common types, etc

zak wrote:

Thanks! I've got this in my todo list now.

zak wrote:

I there any reason that we shouldn't drop PHPDoc compatibility?

  • We generate the docs (which means that most people don't need to generate docs)
  • The devs that do want to generate docs will usually use mwdocgen.php
  • The devs that don't want to use mwdocgen.php or doxygen will have to put in an extra step of converting from Doxygen syntax to whatever syntax they want to use

Assignee: Zak -> Default (Wikibugs-l)

[[mw:Manual:Coding_conventions/PHP#Comments_and_documentation]] seems to be pretty clear about this today. Closing.