> 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.
Okay, this was something I wasn't sure about, but I thought it might be the case. > > 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. Perhaps. I think some sort of "weight" might give the publisher options while also introducing more complexity to the process. > > ....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? I meant instead of what I proposed up there: @doktor-start type:method, method:methodName @doktor-start type:codeblock, codeblock:blockName we have something like: @doktor-start type:codeblock, name:blockName @doktor-start type:method, name:methodName > > 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 sitemap > scenario: 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. > I think that these make more sense and give me a good place to start thinking from, but I'm not sure that with my limited experience with Cocoon I could develop a comprehensive listing. Elaboration of more cases would be helpful. > 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. I always have believed that a dynamic use was if not the end goal for this project it was at least the target for RefDoc in the future. We still have a month to complete whatever it is you'd like and perhaps I could better achieve it if I knew what you had in mind? Although, I'd like to finish even if it isn't before September. Robert
