Hi Robert,Thanks for your analysis - I hope others are going to answer as well, but here are at least my comments:
....I've created several types and other proposed 'well-defined' bits
of
metadata to assist the publishing of these documents into a nice
format and easing the pain of parsing out such information. The types
are:
*method* - this type is for documenting methods or functions
*package* - this type indicates that the comment contains only the
package string for the file and perhaps the leading 'package'
declaration in java or a trailing semicolon
*class-declaration* - this type contains only the class declaration
(and maybe the trailing '{')
*codeblock* - this type is for indicating that the comment contains
code for publishing purposes
ok - my view was a more high-level one than classes and methods, which are adequately covered by the javadocs. These are certainly useful though, but see the proposed use-cases below for a more component-oriented view.
*name* - this type indicates the 'name' of the document of thing being documented under the current key (or specified key for this name *warning* - this type expresses warnings*example* - this type is used to indicate that the comment contains an example*details* - this type must include another piece of metadata indicating what it is detailing more on this in a minute
ok
*variable* - this type is used to document a variable or parameter
ok, we'll need to be more detailed here I think, differentiating sitemap parameters, component configuration parameters, etc.
*description* - this type is used to describe what the purpose of the current thing being documented is as per the current/specified key
ok
*see-also* - this type specifies that it contains a listing of doktor keys that you might also want to look at/search for
ok, this is a very important one.
A few new pieces of metadata:
...
*filetype* - this is usually supplied with the key for the document and indicates what kind of document it is which may be used in a publishing context...
ok, this will be needed for example to republish XML snippets as XML I assume.
Issue #1: The need to associate a codeblock with an example comes from publishing interests. If I have an example with a block of text explaining things and then a demostration in code then without separating them but keeping them associated publishing it correctly becomes a nightmare. I'm afraid though that this may introduce too much complexity to deal with...
The sorting of snippets to build the final document will be a problem as soon as there are more than a few snippets. Maybe introducing an "order number" metadata attribute would help and not be too hard to manage? We could then rearrange the snippets be changing their order numbers, while keeping the overall order based on the snippet types.
....Issue #2: Of course simple having to index so many different metadata keys might be annoying and they should perhaps all be changed to one 'id' or 'name' field. I feel this should be done.
I'm not sure what you mean here, can you elaborate or give an example?
...Issue #3: I figured that the layout of the neutral XML would be similar to how a javadoc document is arranged with the name and packge followed by a description and then examples/methods/variables followed finally by details and perhaps codeblocks. This may be too similar to javadoc, however and I'd like input on formatting decisions...
Starting from a javadoc model is certainly good.
...Finally, any further comments, ideas, or discussion is welcomed...
I'm just going to add a few brief use-cases, or rather a few example questions that I'd like refdoc-generated documentation to answer:
a) What is the FileGenerator?scenario: search the refdoc for "FileGenerator" or navigate the refdoc: refdoc/components/FileGenerator
b) Which generator can read URLs through a proxy?scenario: full-text search for a refdoc document from the "components" collection, containing both the "URL" and "proxy" words.
c) What sitemap parameters can be used for the FileGenerator?scenario: find the document as in a), the document contains a list of parameters build from "sitemap-parameter" metadata elements found in doktor comments. The parameter descriptions stay up to date as the @doktor comments are right next to the source code which reads the parameter, so people remember to keep them up to date.
d) I need an example of how to use the HtmlTransformer in a sitemapscenario: search the refdoc for a snippet ot type "sitemap-example" where property "component-name" is HtmlGenerator. The snippet points to its "parent document" which describes the HtmlGenerator.
It might be good to elaborate on these use-cases and maybe document them in a text file in the refdoc block, but for now I hope they help clarifiy the needs and priorities.
Note that these assume a dynamic search of the refdoc index - I think the full power of the refdoc will be available only when querying the Lucene index directly, as is done in some of these use-cases, but the document-oriented version (that will probably be published as static HTML pages) will contain the same information, only with less precise searches. The Lucene index will be available to people who start Cocoon on their own machines anyway, so I think having to use the Lucene index for precise queries is not a big problem.
-Bertrand
smime.p7s
Description: S/MIME cryptographic signature
