1#
2# Copyright 2010 Free Software Foundation, Inc.
3#
4# This file was generated by gr_modtool, a tool from the GNU Radio framework
5# This file is a part of gr-howto
6#
7# GNU Radio is free software; you can redistribute it and/or modify
8# it under the terms of the GNU General Public License as published by
9# the Free Software Foundation; either version 3, or (at your option)
10# any later version.
11#
12# GNU Radio is distributed in the hope that it will be useful,
13# but WITHOUT ANY WARRANTY; without even the implied warranty of
14# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
15# GNU General Public License for more details.
16#
17# You should have received a copy of the GNU General Public License
18# along with GNU Radio; see the file COPYING.  If not, write to
19# the Free Software Foundation, Inc., 51 Franklin Street,
20# Boston, MA 02110-1301, USA.
21#
22"""
23Classes providing more user-friendly interfaces to the doxygen xml
24docs than the generated classes provide.
25"""
26from __future__ import absolute_import
27from __future__ import unicode_literals
28
29import os
30
31from .generated import index
32from .base import Base
33from .text import description
34
35class DoxyIndex(Base):
36    """
37    Parses a doxygen xml directory.
38    """
39
40    __module__ = "gnuradio.utils.doxyxml"
41
42    def _parse(self):
43        if self._parsed:
44            return
45        super(DoxyIndex, self)._parse()
46        self._root = index.parse(os.path.join(self._xml_path, 'index.xml'))
47        for mem in self._root.compound:
48            converted = self.convert_mem(mem)
49            # For files and namespaces we want the contents to be
50            # accessible directly from the parent rather than having
51            # to go through the file object.
52            if self.get_cls(mem) == DoxyFile:
53                if mem.name.endswith('.h'):
54                    self._members += converted.members()
55                    self._members.append(converted)
56            elif self.get_cls(mem) == DoxyNamespace:
57                self._members += converted.members()
58                self._members.append(converted)
59            else:
60                self._members.append(converted)
61
62
63def generate_swig_doc_i(self):
64    """
65    %feature("docstring") gr_make_align_on_samplenumbers_ss::align_state "
66    Wraps the C++: gr_align_on_samplenumbers_ss::align_state";
67    """
68    pass
69
70
71class DoxyCompMem(Base):
72
73
74    kind = None
75
76    def __init__(self, *args, **kwargs):
77        super(DoxyCompMem, self).__init__(*args, **kwargs)
78
79    @classmethod
80    def can_parse(cls, obj):
81        return obj.kind == cls.kind
82
83    def set_descriptions(self, parse_data):
84        bd = description(getattr(parse_data, 'briefdescription', None))
85        dd = description(getattr(parse_data, 'detaileddescription', None))
86        self._data['brief_description'] = bd
87        self._data['detailed_description'] = dd
88
89    def set_parameters(self, data):
90        vs = [ddc.value for ddc in data.detaileddescription.content_]
91        pls = []
92        for v in vs:
93            if hasattr(v, 'parameterlist'):
94                pls += v.parameterlist
95        pis = []
96        for pl in pls:
97            pis += pl.parameteritem
98        dpis = []
99        for pi in pis:
100            dpi = DoxyParameterItem(pi)
101            dpi._parse()
102            dpis.append(dpi)
103        self._data['params'] = dpis
104
105
106class DoxyCompound(DoxyCompMem):
107    pass
108
109class DoxyMember(DoxyCompMem):
110    pass
111
112class DoxyFunction(DoxyMember):
113
114    __module__ = "gnuradio.utils.doxyxml"
115
116    kind = 'function'
117
118    def _parse(self):
119        if self._parsed:
120            return
121        super(DoxyFunction, self)._parse()
122        self.set_descriptions(self._parse_data)
123        self.set_parameters(self._parse_data)
124        if not self._data['params']:
125            # If the params weren't set by a comment then just grab the names.
126            self._data['params'] = []
127            prms = self._parse_data.param
128            for prm in prms:
129                self._data['params'].append(DoxyParam(prm))
130
131    brief_description = property(lambda self: self.data()['brief_description'])
132    detailed_description = property(lambda self: self.data()['detailed_description'])
133    params = property(lambda self: self.data()['params'])
134
135Base.mem_classes.append(DoxyFunction)
136
137
138class DoxyParam(DoxyMember):
139
140    __module__ = "gnuradio.utils.doxyxml"
141
142    def _parse(self):
143        if self._parsed:
144            return
145        super(DoxyParam, self)._parse()
146        self.set_descriptions(self._parse_data)
147        self._data['declname'] = self._parse_data.declname
148
149    @property
150    def description(self):
151        descriptions = []
152        if self.brief_description:
153            descriptions.append(self.brief_description)
154        if self.detailed_description:
155            descriptions.append(self.detailed_description)
156        return '\n\n'.join(descriptions)
157
158    brief_description = property(lambda self: self.data()['brief_description'])
159    detailed_description = property(lambda self: self.data()['detailed_description'])
160    name = property(lambda self: self.data()['declname'])
161
162class DoxyParameterItem(DoxyMember):
163    """A different representation of a parameter in Doxygen."""
164
165    def _parse(self):
166        if self._parsed:
167            return
168        super(DoxyParameterItem, self)._parse()
169        names = []
170        for nl in self._parse_data.parameternamelist:
171            for pn in nl.parametername:
172                names.append(description(pn))
173        # Just take first name
174        self._data['name'] = names[0]
175        # Get description
176        pd = description(self._parse_data.get_parameterdescription())
177        self._data['description'] = pd
178
179    description = property(lambda self: self.data()['description'])
180    name = property(lambda self: self.data()['name'])
181
182
183class DoxyClass(DoxyCompound):
184
185    __module__ = "gnuradio.utils.doxyxml"
186
187    kind = 'class'
188
189    def _parse(self):
190        if self._parsed:
191            return
192        super(DoxyClass, self)._parse()
193        self.retrieve_data()
194        if self._error:
195            return
196        self.set_descriptions(self._retrieved_data.compounddef)
197        self.set_parameters(self._retrieved_data.compounddef)
198        # Sectiondef.kind tells about whether private or public.
199        # We just ignore this for now.
200        self.process_memberdefs()
201
202    brief_description = property(lambda self: self.data()['brief_description'])
203    detailed_description = property(lambda self: self.data()['detailed_description'])
204    params = property(lambda self: self.data()['params'])
205
206Base.mem_classes.append(DoxyClass)
207
208
209class DoxyFile(DoxyCompound):
210
211    __module__ = "gnuradio.utils.doxyxml"
212
213    kind = 'file'
214
215    def _parse(self):
216        if self._parsed:
217            return
218        super(DoxyFile, self)._parse()
219        self.retrieve_data()
220        self.set_descriptions(self._retrieved_data.compounddef)
221        if self._error:
222            return
223        self.process_memberdefs()
224
225    brief_description = property(lambda self: self.data()['brief_description'])
226    detailed_description = property(lambda self: self.data()['detailed_description'])
227
228Base.mem_classes.append(DoxyFile)
229
230
231class DoxyNamespace(DoxyCompound):
232
233    __module__ = "gnuradio.utils.doxyxml"
234
235    kind = 'namespace'
236
237    def _parse(self):
238        if self._parsed:
239            return
240        super(DoxyNamespace, self)._parse()
241        self.retrieve_data()
242        self.set_descriptions(self._retrieved_data.compounddef)
243        if self._error:
244            return
245        self.process_memberdefs()
246
247Base.mem_classes.append(DoxyNamespace)
248
249
250class DoxyGroup(DoxyCompound):
251
252    __module__ = "gnuradio.utils.doxyxml"
253
254    kind = 'group'
255
256    def _parse(self):
257        if self._parsed:
258            return
259        super(DoxyGroup, self)._parse()
260        self.retrieve_data()
261        if self._error:
262            return
263        cdef = self._retrieved_data.compounddef
264        self._data['title'] = description(cdef.title)
265        # Process inner groups
266        grps = cdef.innergroup
267        for grp in grps:
268            converted = DoxyGroup.from_refid(grp.refid, top=self.top)
269            self._members.append(converted)
270        # Process inner classes
271        klasses = cdef.innerclass
272        for kls in klasses:
273            converted = DoxyClass.from_refid(kls.refid, top=self.top)
274            self._members.append(converted)
275        # Process normal members
276        self.process_memberdefs()
277
278    title = property(lambda self: self.data()['title'])
279
280
281Base.mem_classes.append(DoxyGroup)
282
283
284class DoxyFriend(DoxyMember):
285
286    __module__ = "gnuradio.utils.doxyxml"
287
288    kind = 'friend'
289
290Base.mem_classes.append(DoxyFriend)
291
292
293class DoxyOther(Base):
294
295    __module__ = "gnuradio.utils.doxyxml"
296
297    kinds = set(['variable', 'struct', 'union', 'define', 'typedef', 'enum',
298                 'dir', 'page', 'signal', 'slot', 'property'])
299
300    @classmethod
301    def can_parse(cls, obj):
302        return obj.kind in cls.kinds
303
304Base.mem_classes.append(DoxyOther)
305