VEry good idea,
the php doc is the first stop for me when I need to find out some patterns and usage, so for sure I think it would be good that within the Unity editor, you could comment somehow on a given custom action as well as browse these comments very easily from the action browser or something.
that said, indeed some careful monitoring and moderation will be mandatory, cause within the same php doc, sometime, you wonder if the info is something you can rely on, here it would be required that comments are always testified, verified and maintained, else it will be junk before it's even used properly.
bye,
Jean