1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
|
#pragma once
#include "Value.h"
#include "Visibility.h"
#include "Core/Str.h"
#include "Utils/Exception.h"
namespace storm {
STORM_PKG(core.lang);
class Named;
/**
* Parameter names for use in documentation.
*/
class DocParam {
STORM_VALUE;
public:
// Create.
STORM_CTOR DocParam(Str *name, Value type);
// Parameter name.
Str *name;
// Parameter type.
Value type;
// Output.
void STORM_FN toS(StrBuf *to) const;
};
// To string.
wostream &operator <<(wostream &to, DocParam p);
/**
* Documentation note. Contains a type and a string that is to displayed alongside the name of
* the object. Used for things like return types and inheritance.
*
* A type of 'void' is ignored, which means that this class can be used to represent other kinds
* of information as well.
*/
class DocNote {
STORM_VALUE;
public:
// Create.
STORM_CTOR DocNote(Str *note, Value type);
STORM_CTOR DocNote(Str *note, Named *named);
STORM_CTOR DocNote(Str *note);
// Note.
Str *note;
// Named object.
MAYBE(Named *) named;
// Reference?
Bool ref;
// Show the type at all?
Bool showType;
// Output.
void STORM_FN toS(StrBuf *to) const;
};
// To string.
wostream &operator <<(wostream &to, DocNote n);
/**
* Documentation for a single named entity.
*
* Instances of this class is generally not stored in memory longer than necessary. Rather, each
* 'Named' instance may provide a 'NamedDoc' instance that allows retrieving 'Doc' instances for
* that entity when needed. Documentation is generally browsed by a user, and as such it is
* desirable to load documentation on demand (since we can be fast enough) rather than preemptively.
*
* TODO: Include a reference to the Named or Template we are referring to?
* TODO: Include source position here or in the Named itself.
* TODO: Include a value that allows sorting the documentation for a type in some useful order.
*/
class Doc : public Object {
STORM_CLASS;
public:
// Create.
STORM_CTOR Doc(Str *name, Array<DocParam> *params, MAYBE(Visibility *) v, Str *body);
STORM_CTOR Doc(Str *name, Array<DocParam> *params, DocNote note, MAYBE(Visibility *) v, Str *body);
STORM_CTOR Doc(Str *name, Array<DocParam> *params, Array<DocNote> *notes, MAYBE(Visibility *) v, Str *body);
// Name of this entity.
Str *name;
// Parameters.
Array<DocParam> *params;
// Notes.
Array<DocNote> *notes;
// Visibility of this entity.
MAYBE(Visibility *) visibility;
// Documentation body. Formatted using a format similar to Markdown.
Str *body;
// Deep copy.
virtual void STORM_FN deepCopy(CloneEnv *env);
// Generate a one-line summary of the documentation.
Str *STORM_FN summary() const;
// To string.
virtual void STORM_FN toS(StrBuf *to) const;
};
// Create documentation, infer 'name' and 'notes' from an entity.
Doc *STORM_FN doc(Named *entity, Array<DocParam> *params, Str *body) ON(Compiler);
// Create a dummy documentation block for 'entity'. Used when no NamedDoc is provided.
Doc *STORM_FN doc(Named *entity) ON(Compiler);
/**
* Documentation provider for named entities.
*
* TODO: It would be interesting to be able to query for a 'minimal' documentation object that
* only contains enough information to make the 'summary' interesting. This would mean only
* loading the parameter names and any notes essentially.
*/
class NamedDoc : public ObjectOn<Compiler> {
STORM_ABSTRACT_CLASS;
public:
// Create.
STORM_CTOR NamedDoc();
// Get documentation for this named entity.
virtual Doc *STORM_FN get() ABSTRACT;
};
/**
* Exception for documentation errors.
*/
class EXCEPTION_EXPORT DocError : public Exception {
STORM_EXCEPTION;
public:
DocError(const wchar *msg) {
w = new (this) Str(msg);
}
STORM_CTOR DocError(Str *msg) {
w = msg;
}
virtual void STORM_FN message(StrBuf *to) const {
*to << w;
}
private:
Str *w;
};
}
|
