Earlier this evening I found myself gawking at a strange confusion of letters and symbols that had appeared in my editor. What are these symbols, and where do they come from? What secret geometry governs their arrangement? Just what is this, anyway? I sat and stared, perplexed. The symbols stared back.
Soon my eyes adjusted to the strange contours of the glyphs, and I began to perceive a kind of rhythm or a structure to their ordering. Finally, I lit upon this enchanted hieroglyph: @file Of course! That's what this is -- a file! I wept with joy, and my heart soared with gratitude for this humble Doxygen tag, without which the ontology of our source code would be occult and irretrievable. But soon my rapture gave way to creeping doubts: could we not, after all, do better? I went to the drawing board. After several iterations (all agile, naturally), I came up with two tags that I think are very fine and that I'd like to see us adopt. Consider them: @tag This tag denotes a Doxygen tag. Like '@file', it answers the question, "What is this?". Answer: it is a Doxygen tag. It is not a banana. A car part, neither. If you thought it was a ceiling fan or a Python decorator, you were wrong -- dead wrong. Because it is a Doxygen tag. @comment This tag denotes a comment. It precisely identifies the purpose and discourse of the text which surrounds it. It tells you, "There is wisdom here. Stay a while and listen." Here is a sample file header, demonstrating proper usage of these tags: /** * Example * This file represents an example. * * @file * @ingroup examples * @comment * @tag */ The syntax is economical and expressive; the meaning eloquent and germane. What do you think? Don't worry about the HTML representation for now -- we can worry about those later. --- Ori Livneh o...@wikimedia.org _______________________________________________ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
