[jetpack] apidoc embedded into module sourcecode

[Luca Greco]

Working on bug 555180, I tried to render apidoc (with the current
<api> syntax) embedded into sourcecode instead of using separate
markdown pages,
more details in the comment and the attached diff:

https://bugzilla.mozilla.org/show_bug.cgi?id=555180#c13

--
Luca Greco @ Alca Società Cooperativa
Follow me on http://twitter.com/lucagreco

--
You received this message because you are subscribed to the Google Groups "mozilla-labs-jetpack" group.
To post to this group, send email to mozilla-la...@googlegroups.com.
To unsubscribe from this group, send email to mozilla-labs-jet...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/mozilla-labs-jetpack?hl=en.

[Drew]

IIRC the decision to keep end-user developer documentation out of the
source was deliberate. The reasons were something like, the audience
reading your code is different from the audience of end-user developers;
since the audiences are different, the source shouldn't be cluttered
with end-user developer docs, which are verbose and include examples and
so on; the separation allows people to hack on the docs separately from
the source; and the dynamic nature of JavaScript can sometimes make it
difficult to annotate code in a way intended for doc parsing.

I still agree with all of that, but now that we're into the fourth
release it might be a good time to re-evaluate some things. The one
thing I don't like is that I'm often duplicating things between
in-source docs and the end-user developer docs. That's probably my
fault, since I pushed for Javadoc-style comments in the source to match
Mozilla conventions. I'm not sure if others are following that
convention, but I'd like to drop it.

Drew

On 5/8/10 8:27 AM, Luca Greco wrote:
> Working on bug 555180, I tried to render apidoc (with the current
> <api> syntax) embedded into sourcecode instead of using separate
> markdown pages,
> more details in the comment and the attached diff:
>
> https://bugzilla.mozilla.org/show_bug.cgi?id=555180#c13
>

--

[Dietrich Ayala]

On Sat, May 8, 2010 at 5:28 PM, Drew <a...@mozilla.com> wrote:
> I still agree with all of that, but now that we're into the fourth release
> it might be a good time to re-evaluate some things.  The one thing I don't
> like is that I'm often duplicating things between in-source docs and the
> end-user developer docs.  That's probably my fault, since I pushed for
> Javadoc-style comments in the source to match Mozilla conventions.  I'm not
> sure if others are following that convention, but I'd like to drop it.

I prefer your initial instinct here. It's not fun digging around in
those modules that have zero code documentation.

If we don't use Luca's work here, I think we should continue the
Javadoc requirement, even at the cost of some annoying duplication.

[Drew]

Undocumented modules are a whole other problem, I agree. But if I
thoroughly document my module in the end-user docs, why should I have to
duplicate some of that in the source? What I would like to be able to
say is true is, "Jetpack modules have really good end-user docs. For
that reason, the only comments in the source we need are those that
document implementation."

Drew

[Luca Greco]

I understand Drew's motivations, and I like clean sourcecode too :-)
but minimal apidoc embedded into sourcecode (without examples)
could help to keep apidoc in sync with the real source code.

Examples, Tutorials and Howto could be added as simple markdown doc pages
and link apidoc and doc pages using simple html links.

A diagram can be better them of thousands words (especially thanks to my
horrible english :-P):

https://docs.google.com/drawings/edit?id=1yUOA6uE5_2ON4fLl4MOz2nUJB3-t-Ex63LppAgVXHVg&hl=en

I don't want to force an unmotivated change, if there's not any
interests into this feature/change
I'll stop to hack on this without any problem and I'll take some other
bugzilla ticket.

Otherwise I'll continue to make some improvements to the prototype to
get it better.

--
Luca Greco @ Alca Società Cooperativa
Follow me on http://twitter.com/lucagreco

[fiveinchpixie]

Hi!

I've been working with Daniel on a way to display a list of the
available APIs in the package specification via the docs server. My
first thought was to try and leverage the markdown to pull the
existing Markdown files from the docs directory onto a single page.
But after some thought, figured that it would be visually messy and
potentially unhelpful.

I also think it's valuable to have good end-user documentation.

With this in mind, we could use the work that Luca is putting in to
create a clean render of the apidoc to a package API reference and
keep the end-user docs where they are in Markdown.

Which is what I believe Luca's diagram is getting at...

What do you think?

/Noelle
Documentation Czar

[Luca Greco]

On Thu, May 13, 2010 at 2:34 AM, fiveinchpixie <fivein...@gmail.com> wrote:
> Hi!
>
> I've been working with Daniel on a way to display a list of the
> available APIs in the package specification via the docs server. My
> first thought was to try and leverage the markdown to pull the
> existing Markdown files from the docs directory onto a single page.
> But after some thought, figured that it would be visually messy and
> potentially unhelpful.
>
> I also think it's valuable to have good end-user documentation.
>
> With this in mind, we could use the work that Luca is putting in to
> create a clean render of the apidoc to a package API reference and
> keep the end-user docs where they are in Markdown.
>
> Which is what I believe Luca's diagram is getting at...

It's my point of view!

In the mean time I will change the original "code illuminated" module
view into a simple
"syntax highlighted sourcecode" module view.

This is a very simple change to the current documentation system and
don't overlaps current features
or policies.

> What do you think?
>
> /Noelle
> Documentation Czar

Happy Jetpack-ing,
rpl

--
Luca Greco @ Alca Società Cooperativa
Follow me on http://twitter.com/lucagreco