Hi all, We have recently been looking at the documentation for Infusion Framework API functions. We would like to move the docs from the wiki to comments in the source code. We will then use Steve's infusion-tags tool to generate HTML from the source code.
Last week, I was having a look at the existing Framework API documentation in the wiki and in some cases we have more information in the wiki than would comfortably be expressed in source code comments. For example: http://wiki.fluidproject.org/display/docs/fluid.fetchResources and http://wiki.fluidproject.org/display/docs/fluid.messageResolver each contain tables and source code blocks. When we first discussed this issue at last week's community meeting, we proposed making infusion-docs Markdown pages for API functions such as those above; for pages with information that we do not want to move to the source code. We proposed inserting hyperlinks into the source code comments of the form "For more information see <a href="...">...</a>" which would point to the corresponding doc page. My thinking is now that putting hyperlinks directly into the source code is a little too fragile. There would be ways to deal with this fragility in the future, but initially, I would like to propose that we instead point the user to a doc page simply in text: "For more information see the ... page in the Infusion documentation". In the future, I can see us potentially augmenting the infusion-docs tool to process an extra configuration table which specifies which API functions have doc pages. The tool would then insert appropriate links into the generated HTML, rather than the URLs being hardcoded into the source code. Does directing the user with text and without an automated hyperlink seem like a reasonable initial solution? Please let me know. Thanks, Simon
_______________________________________________________ fluid-work mailing list - [email protected] To unsubscribe, change settings or access archives, see http://lists.idrc.ocad.ca/mailman/listinfo/fluid-work
