On 6-Mar-09, at 2:20 AM, [email protected] wrote:
although auto-generated documentation can
never be an adequate replacement for a complete manually written
component guide, it is no reason not to have some....I don't think
anyone is suggesting that moving to autogenerated docs implies
destroying pages like "List Reorderer API" and their kin? Those
were an awful lot of work to produce that indeed it would be silly
to stuff into a single .js file
Yes, lots of work *did* go into creating those pages!! I'd love to
find a way to not waste all that effort.
Ok, so lets follow this though a bit: Suppose we have autogenerated
API docs, as well more detailed explanations elsewhere.
Sticking with the List Reorderer API page as our example, there is
information on that page which would be duplicated by autogenerated
API docs, i.e. the function signature and basic parameter
descriptions. Would we remove that info from the wiki page? If we
didn't, then we'd have duplicated information that would need to be
kept in sync.
We would still need to deal with 'release' vs 'trunk' versions of the
wiki pages. As the API settles down and changes much less often, this
will become easier. And if we don't continue to maintain past
versions, but simply have trunk and release, it would be much easier
to simply keep the trunk versions up-to-date as we work, then at
release time, replace the older release version with a new snapshot.
Also, we'd need links between the auto-generated API page and the more
detailed explanations on the wiki. At release time, when a snapshot is
taken of the trunk wiki pages, links there to the trunk API docs would
have to be updated to reference the release version. Also, any links
in the autogenerated docs to the wiki would have to be referencing the
correct version of the wiki docs.
All of these 'versioning the wiki docs' issues would be much
simplified if the manually created docs were not on the wiki, but also
in SVN in some format, e.g. HTML, XML, etc. Perhaps Markdown might be
of help here:
http://daringfireball.net/projects/markdown/
--
Anastasia Cheetham [email protected]
Software Designer, Fluid Project http://fluidproject.org
Adaptive Technology Resource Centre / University of Toronto
_______________________________________________________
fluid-work mailing list - [email protected]
To unsubscribe, change settings or access archives,
see http://fluidproject.org/mailman/listinfo/fluid-work
