I don't think that our comment syntax in the Annotated HTML Renderer is API per see. he Annotated HTML parser/renderer are supposed to be for internal user (we probably made a mistake of not having them in the internal package initially). We created them only for our WYSIWYG use case. I'd be in favor of voting a "breakage" here as I doubt anyone else is using them.

Now, it's true that it's not great that we have to modify our rendering to escape comments when the spec doesn't mandate it, and it would be nicer to handle it at the WYSIWYG code level. I understand from the comments above that it doesn't seem easy though (even if iterating a DOM tree to change comments doesn't seem like something too hard to do). OTOH since the Annotated HTML Renderers are coded for the WYSIWYG use case only, I guess it's not such a big problem to change the way they encode the comments.