File: Synopsis/Processors/Comments/Translator.py
 1#
 2# Copyright (C) 2006 Stefan Seefeld
 3# All rights reserved.
 4# Licensed to the public under the terms of the GNU LGPL (>= 2),
 5# see the file COPYING for details.
 6#
 7
 8from Synopsis import ASG
 9from Synopsis.DocString import DocString
10from Synopsis.Processor import Processor, Parameter
11from Filter import *
12
13class Translator(Processor, ASG.Visitor):
14    """A Translator translates comments into documentation."""
15
16    filter = Parameter(SSFilter(), 'A comment filter to apply.')
17    processor = Parameter(None, 'A comment processor to run.')
18    markup = Parameter('', 'The markup type for this declaration.')
19    concatenate = Parameter(False, 'Whether or not to concatenate adjacent comments.')
20    primary_only = Parameter(True, 'Whether or not to preserve secondary comments.')
21
22    def process(self, ir, **kwds):
23
24        self.set_parameters(kwds)
25        self.ir = self.merge_input(ir)
26        if self.filter:
27            self.ir = self.filter.process(self.ir)
28        if self.processor:
29            self.ir = self.processor.process(self.ir)
30
31        for decl in self.ir.asg.declarations:
32            decl.accept(self)
33
34        return self.output_and_return_ir()
35
36
37    def visit_declaration(self, decl):
38        """Map comments to a doc string."""
39
40        comments = decl.annotations.get('comments')
41        if comments:
42            text = None
43            if self.primary_only:
44                text = comments[-1]
45            elif self.combine:
46                text = ''.join([c for c in comments if c])
47            else:
48                comments = comments[:]
49                comments.reverse()
50                for c in comments:
51                    if c is not None:
52                        text = c
53                        break
54            doc = DocString(text or '', self.markup)
55            decl.annotations['doc'] = doc
56