On Thursday 24 March 2005 19:43, Joel de Guzman wrote: > > I can see more clearly how the second model (presented by Jo�o) would > > work, but I don't like adding the snippet delimiters in comments. It > > cuts across the Doxygen comment processing. Remember also that the > > comment syntax will be different for different source modes. That said, > > James Fowler has already gone some way towards implementing inclusion > > of snippets. > > I agree. When Joao and I had the chat, I wasn't quite anxious > about the include snippet proposal. I didn't have a strong > case against it at the time and thought that both solutions > are orthogonal anyway. Now, it seems that you provided a > strong case against it: that 1) Qbk needs to know something about > the target language and each markup syntax will be different for > different langauges. This is unwieldy. 2) I too do not like > special tagged comments in my source code. In that sense, I am > not quite fond of Doxygen, in fact.
For me, "include source" model is superior to "source inside docs" model. The first reason is that Emacs won't indent source inside docs propertly, and won't even syntax highlight them properly. I'm not kidding -- this is rather important. And in general, modifying code embedded inside docs is rather hard. I've tried this once and this was just horrible -- when I wanted to change the implementation I had to find relevant snippets scattered all over the document and modify them. And with docs and source interleaved, the structure of the program gets lost. Some non-intrusive markup in source file, plus inclusion mechanism, would work much better for me. OTOH, I've got my bad experience when implementing some nontrivial algorithm, maybe for documenting library examples interleaved docs and source are not as bad. - Volodya ------------------------------------------------------- SF email is sponsored by - The IT Product Guide Read honest & candid reviews on hundreds of IT Products from real users. Discover which products truly live up to the hype. Start reading now. http://ads.osdn.com/?ad_ide95&alloc_id396&op=click _______________________________________________ Boost-docs mailing list [email protected] Unsubscribe and other administrative requests: https://lists.sourceforge.net/lists/listinfo/boost-docs
