[wp-hackers] Inline documentation

[Robert Deaton]

On 2/20/06, Matt Mullenweg <m at mullenweg.com> wrote:
> If the goal is making things more accessible for new developers, than we
> would be stupid to not have a human readable, searchable, and thorough
> online version.

The codex has already tried to do this, and failed miserably.

> I don't think we should auto-generate developer documentation for the
> same reasons we don't auto-generate the UI:

We don't autogenerate UI because it has to be something completely
understandable to an end user. This, is a seperate issue, for
developers, and tons of open source communities throughout the world
have already proven that PHPDoc or similar is a great resource for
developers, its UI has already been well thought out, and proven to
work.

> http://daringfireball.net/2004/04/spray_on_usability

I don't know what the heck this has to do with anything, really.

> If the goal is just to get javadoc-formatted style cruft in front of
> every function in WordPress, let's state that directly. I think there is
> a very small percentage of users who intuitively grasp javadoc
We're talking about developers, not users, and very few people
intuitively grasp anything, but the learning curve is incredibly
small, and the benefit is large.

<snip>
> It doesn't educate anybody,
How so? Sure, for you, having been the lead developer of the project
for many years, I can see not understanding where the benefit of this
comes in, but for the rest of the world that doesn't have function
names, their uses, and the argument orders memorized, a quick way to
find out without having to pull up a webbrowser or a seperate program
and go searching is highly appreciated, even for a few of us who have
been around here for years as well, as you can see from the rest of
the thread. The new developers can in the mean time cut straight to
developing, and when they find a function that they're unsure of, they
read the inline documentation and move along, instead of trying to
figure out what the heck some of the sloppy functions in the core do
(yes, i said it).


--
--Robert Deaton
http://somethingunpredictable.com